Zellij 配置文件基础与常用选项

编程技术 2026-05-18 7 分钟阅读

Zellij 使用 KDL（KDL Document Language）作为配置文件格式，这是一种简洁、可读性强的节点式文档语言。通过配置文件，你可以定制 Zellij 的几乎所有行为——从界面主题到 Shell 选项，从会话管理到键位绑定。本文将带你全面了解配置文件的结构和常用选项。

一、配置文件位置与格式

KDL 格式简介

Zellij 的配置文件使用 KDL 格式，主要特点包括：

  • 使用 // 进行单行注释。
  • 节点以名称开头，后跟参数和子节点块。
  • 参数使用空格分隔，字符串值用双引号包裹。
  • 子节点放在大括号 {} 中。

配置文件位置

默认的配置文件路径为：

~/.config/zellij/config.kdl

如果你是第一次使用 Zellij 或者想从头开始配置，可以使用以下命令生成一份包含所有选项及默认值的完整配置文件：

zellij setup --dump-config > ~/.config/zellij/config.kdl

生成的文件中每个选项都有详细的注释说明，是最权威的配置参考文档。

配置目录搜索优先级

Zellij 按以下优先级搜索配置目录（高优先级覆盖低优先级）：

  1. 命令行参数：zellij --config-dir /path/to/config/
  2. 环境变量：ZELLIJ_CONFIG_DIR
  3. 用户目录：~/.config/zellij/
  4. 系统目录：/etc/zellij/

你也可以直接指定具体的配置文件路径，而非整个目录：

zellij --config /path/to/my-config.kdl

或通过环境变量：

export ZELLIJ_CONFIG_FILE=/path/to/my-config.kdl

热重载

Zellij 支持配置文件热重载：当你修改并保存 config.kdl 后，正在运行的 Zellij 会话会自动检测到变更并重新加载配置，无需重启。这意味着你可以在不中断工作的情况下调整主题、键位绑定等设置。

二、界面设置

界面相关的配置控制 Zellij 的视觉呈现方式。

主题

// 使用内置主题
theme "dracula"

设置主题会立即改变面板边框、状态栏、标签栏等所有 UI 元素的颜色。

默认布局

// 指定启动时的默认布局
default_layout "compact"

面板边框

// 显示或隐藏面板边框
pane_frames {
    rounded_corners true
    hide_session_name false
}

rounded_corners 让面板边框使用圆角样式，hide_session_name 控制是否在 UI 中隐藏当前会话名称。

其他界面选项

选项 默认值 说明
simplified_ui false 启用简化 UI，减少边框和装饰元素
styled_underlines true 在终端支持时使用样式化下划线
pane_frames true 是否显示面板边框

三、Shell 和面板设置

以下选项控制新面板的默认行为：

选项 默认值 说明
default_shell 系统默认 shell 新面板使用的 shell 程序，如 "zsh"、"/bin/fish"
default_cwd 当前目录 新面板的默认工作目录
default_mode "normal" 启动时的默认键位模式
mouse_mode true 是否启用鼠标支持（点击切换面板、滚动等）
scroll_buffer_size 10000 每个面板的回滚缓冲区行数
copy_command 自动检测 自定义复制到剪贴板的命令，如 "xclip -selection clipboard"
copy_clipboard "primary" 剪贴板选择方式："primary" 或 "clipboard"

配置示例：

// ~/.config/zellij/config.kdl
default_shell "fish"
default_cwd "/home/user/projects"
mouse_mode true
scroll_buffer_size 50000
copy_command "xclip -selection clipboard"

四、会话设置

会话相关的配置已在会话复活一文中有所涉及，这里做一个完整汇总：

选项 默认值 说明
session_serialization true 是否启用会话序列化
auto_layout true 复活时自动应用保存的布局
on_force_close "quit" 关闭最后一个面板时的行为："quit" 退出、"detach" 分离

on_force_close 是一个容易被忽视但很实用的选项。设为 "detach" 后，当你误操作关闭了最后一个面板时，会话不会退出而是自动分离，你可以随时重新连接。

五、Web 服务器配置

Zellij 内置了一个可选的 Web 服务器功能，允许通过浏览器远程查看和管理会话。

// 启用 Web 服务器
web_server false
web_server_ip "127.0.0.1"
web_server_port 8080

// SSL 证书（可选，用于 HTTPS）
// web_server_ssl_cert "/path/to/cert.pem"
// web_server_ssl_key "/path/to/key.pem"

默认情况下 Web 服务器是关闭的。如果启用，建议仅绑定到本地地址（127.0.0.1）以确保安全。如果需要远程访问，建议配合 SSL 证书使用。

六、环境变量与自定义目录

env 块

你可以通过 env 块为 Zellij 会话中的所有面板设置环境变量：

env {
    EDITOR "nvim"
    LANG "en_US.UTF-8"
    RUST_BACKTRACE "1"
}

这些环境变量会在每个新面板启动时自动设置，效果等同于在 shell 配置中 export。

自定义目录

// 自定义布局文件目录
layout_dir "/home/user/.config/zellij/layouts"

// 自定义主题文件目录
theme_dir "/home/user/.config/zellij/themes"

通过指定自定义目录，你可以将布局和主题文件组织在你喜欢的任意位置，方便版本管理和团队共享。

返回博客列表