# 使用 Lua 配置

## 配置的生效范围

Pebrel 的配置命令可以创建、解析和校验 Lua 文件。正式 GPUI 桌面界面与旧渲染器读取的字段范围不同：**校验通过，不等于每个字段都已被当前界面使用。**

按 2026-10-21 的主线核对，GPUI 从 Lua 启动配置中读取窗口行列尺寸；主题、字体、快捷键和默认 Shell，日常使用请从应用设置调整。不要依赖通用 Lua 文档中的环境变量、Shell Profile 或全面热重载示例来控制当前 GPUI 界面。

## 初始化与检查

```sh
pebrel config init --language zh-CN
pebrel config check
```

第一条生成带中文注释的配置，第二条检查语法与字段。初始化默认不会覆盖已有文件。以命令输出的实际路径为准。

## 设置启动窗口尺寸

```lua
local pebrel = require 'pebrel'
local config = pebrel.config_builder()

config.window = {
  dimensions = { columns = 120, lines = 32 }
}

return config
```

行与列同时设置为正数。保存并通过检查后，在新启动的应用窗口核对尺寸；现有窗口不会因此自动变大。工作区恢复与界面偏好也可能影响最终布局。

## 检查指定文件

```sh
pebrel config check --config-file /path/to/pebrel.lua
```

将路径替换成实际文件。检查命令不需要打开应用窗口。

## 配置目录

| 系统 | 标准目录 |
| --- | --- |
| Windows | `%APPDATA%\Pebrel` |
| macOS | `~/Library/Application Support/Pebrel` |
| Linux | `$XDG_CONFIG_HOME/pebrel`，未设置时为 `~/.config/pebrel` |

环境变量、便携配置和显式参数可能指定其他位置。GUI 偏好、终端 Profile 和 Lua 配置属于不同的数据来源；不能把 GUI 的 `pebrel_settings.txt` 内容直接粘进 Lua 文件。

## 保存后如何确认

先运行配置检查，再验证受支持的实际功能。GPUI 的这条启动配置路径不会全面热重载 Lua 选项；修改启动尺寸后重新启动窗口。调整外观或 Shell 时，优先使用设置页面并新建终端验证。

## 相关配置说明

更多示例见[配置示例](/docs/config-examples/)。完整字段解析与旧路径兼容说明见仓库的 [Lua 配置参考](https://github.com/Kuddev/pebrel/blob/c57f4c9e12d30645117ac90c9df46cc71379a120/docs/lua-configuration.md)，使用时同时核对当前渲染器的生效范围。

> **说明**
> Lua 配置可以执行本地代码。使用他人的配置前先阅读内容。配置语言的后续演进以实际发布为准。

---
Source: Kuddev/pebrel PR #291, WilliamWang1721 and Pebrel contributors.
Adapted for pebrel.com. License: GPL-3.0.
