环境变量

OpenTUI 在运行时读取环境变量。Bun 会自动加载 .env 文件，因此你可以在 shell 中或在 .env 文件中设置这些变量。

变量

变量名	类型	默认值	说明
`OTUI_TS_STYLE_WARN`	`string`	`false`	启用缺失语法样式的警告
`OTUI_TREE_SITTER_WORKER_PATH`	`string`	`""`	Tree-sitter worker 的路径
`XDG_CONFIG_HOME`	`string`	`""`	用户配置文件的基础目录
`XDG_DATA_HOME`	`string`	`""`	用户数据文件的基础目录
`OTUI_PALETTE_IDLE_TIMEOUT_MS`	`number`	`300`	调色板查询后无响应的毫秒数，超过后将回退
`OTUI_DEBUG_FFI`	`boolean`	`false`	启用 FFI 绑定的调试日志
`OTUI_SHOW_STATS`	`boolean`	`false`	在启动时显示调试浮层
`OTUI_TRACE_FFI`	`boolean`	`false`	启用 FFI 绑定的跟踪
`OPENTUI_FORCE_WCWIDTH`	`boolean`	`false`	使用 wcwidth 进行字符宽度计算
`OPENTUI_FORCE_UNICODE`	`boolean`	`false`	在终端能力中强制启用 Mode 2026 Unicode 支持
`OPENTUI_GRAPHICS`	`boolean`	`true`	启用 Kitty 图形协议检测
`OPENTUI_FORCE_NOZWJ`	`boolean`	`false`	使用 no_zwj 宽度计算方法（不使用 ZWJ 连接的 Unicode）
`OPENTUI_LIBC`	`string`	未设置	选择 Linux 原生 libc 包（`glibc`、`musl`）
`OPENTUI_FORCE_EXPLICIT_WIDTH`	`string`	-	强制显式宽度检测（`true`/`1` 或 `false`/`0`）
`OPENTUI_NOTIFICATION_PROTOCOL`	`string`	`auto`	强制通知协议（`osc9`、`osc777`、`osc99`、`none`）
`OPENTUI_NOTIFICATIONS`	`boolean`	`true`	设为 false 时禁用终端通知检测
`OTUI_USE_CONSOLE`	`boolean`	`true`	为内置浮层启用全局 `console.*` 捕获
`SHOW_CONSOLE`	`boolean`	`false`	在启动时打开内置控制台浮层
`OTUI_DUMP_CAPTURES`	`boolean`	`false`	从退出处理程序中转储捕获的 stdout 和控制台缓存
`OTUI_NO_NATIVE_RENDER`	`boolean`	`false`	跳过 Zig/原生帧渲染器
`OTUI_USE_ALTERNATE_SCREEN`	`boolean`	未设置	设置后强制使用备用屏幕或主屏幕模式
`OTUI_OVERRIDE_STDOUT`	`boolean`	未设置	设置后强制 stdout 捕获/透传路由
`OTUI_DEBUG`	`boolean`	`false`	捕获所有原始 stdin 输入用于调试

注意事项

OPENTUI_FORCE_EXPLICIT_WIDTH=false 会跳过旧终端上的 OSC 66 查询。
Linux 默认使用 glibc 原生包。在导入 OpenTUI 之前设置 OPENTUI_LIBC=musl，或在独立构建时将 process.env.OPENTUI_LIBC 定义为 "musl"，即可使用 musl 原生包。参见独立可执行文件。
OPENTUI_NOTIFICATION_PROTOCOL=none 禁用通知。协议覆盖仅应在终端检测无法识别受支持的通知协议时使用。
OPENTUI_NOTIFICATIONS=0、false 或 off 可禁用通知，且不会影响其他终端能力检测。
OTUI_PALETTE_IDLE_TIMEOUT_MS 用于限制调色板检测的等待时间，当终端报告支持 OSC 但不响应后续颜色查询时生效。
使用 OTUI_USE_CONSOLE=false 可禁用全局 console.* 捕获。consoleMode 仅更改浮层面板。
OTUI_USE_ALTERNATE_SCREEN=false 强制使用 "main-screen"；true 强制使用 "alternate-screen"。设置后会覆盖 screenMode。
OTUI_OVERRIDE_STDOUT=true 仅在 "split-footer" 模式下捕获；false 强制透传。设置后会覆盖 externalOutputMode。
OTUI_NO_NATIVE_RENDER 仍然会运行渲染循环。在 "split-footer" 模式下，当前输出刷新路径仍然可能发出 ANSI 光标移动和清除序列。
OTUI_DUMP_CAPTURES 从渲染器退出处理程序中运行。直接调用 renderer.destroy() 本身不会触发此操作。