zellij-guide
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseZellij Guide — Personal Reference
Zellij 指南 — 个人参考
Binary:(installed via Nix flake) Config:/Users/wcygan/.nix-profile/bin/zellij→ symlinked to~/Development/dotfiles/config/zellij/config.kdlLayouts:~/.config/zellij/config.kdl~/Development/dotfiles/config/zellij/layouts/
For exhaustive action/option/layout reference, see reference.md.
二进制文件:(通过Nix flake安装) 配置文件:/Users/wcygan/.nix-profile/bin/zellij→ 软链接至~/Development/dotfiles/config/zellij/config.kdl布局文件:~/.config/zellij/config.kdl~/Development/dotfiles/config/zellij/layouts/
如需完整的操作/选项/布局参考,请查看reference.md。
Quick Start
快速开始
bash
zellij # New session (random name)
zellij -s work # New named session
zellij -l dev # New session with dev.kdl layout
zellij ls # List sessions (including exited)
zellij a work # Attach to "work" session
zellij d work # Delete exited sessionbash
zellij # 新建会话(随机名称)
zellij -s work # 新建命名会话
ezellij -l dev # 使用dev.kdl布局新建会话
zellij ls # 列出所有会话(包括已退出的)
zellij a work # 连接到“work”会话
ezellij d work # 删除已退出的会话Your Keybinds (clear-defaults=true, vim-style)
你的快捷键设置(clear-defaults=true,Vim风格)
Your config uses — only these bindings exist:
clear-defaults=true你的配置使用 — 仅以下快捷键生效:
clear-defaults=trueNormal Mode (default)
普通模式(默认)
| Key | Action |
|---|---|
| Move focus / tab left |
| Move focus / tab right |
| Move focus down |
| Move focus up |
| New pane (auto direction) |
| New pane down |
| New pane right |
| New pane down |
| New pane right |
| Close focused pane |
| Toggle fullscreen |
| New tab |
| Close tab |
| Go to tab 1-5 |
| Quit |
| Detach |
| → Pane mode |
| → Resize mode |
| → Move mode |
| → Locked mode |
| → Scroll mode |
| 按键 | 操作 |
|---|---|
| 向左移动焦点/切换标签页 |
| 向右移动焦点/切换标签页 |
| 向下移动焦点 |
| 向上移动焦点 |
| 新建面板(自动方向) |
| 向下新建面板 |
| 向右新建面板 |
| 向下新建面板 |
| 向右新建面板 |
| 关闭当前焦点面板 |
| 切换全屏模式 |
| 新建标签页 |
| 关闭标签页 |
| 切换到第1-5个标签页 |
| 退出Zellij |
| 断开会话连接 |
| → 面板模式 |
| → 调整大小模式 |
| → 移动面板模式 |
| → 锁定模式 |
| → 滚动模式 |
Pane Mode (Ctrl p
to enter, Esc
to exit)
Ctrl pEsc面板模式(按Ctrl p
进入,Esc
退出)
Ctrl pEsc| Key | Action |
|---|---|
| Move focus |
| New pane |
| Close pane |
| Toggle fullscreen |
| Toggle floating panes |
| Toggle embed/float |
| Rename pane |
| 按键 | 操作 |
|---|---|
| 移动焦点 |
| 新建面板 |
| 关闭面板 |
| 切换全屏 |
| 切换浮动面板显示 |
| 切换嵌入/浮动模式 |
| 重命名面板 |
Resize Mode (Ctrl r
to enter, Esc
to exit)
Ctrl rEsc调整大小模式(按Ctrl r
进入,Esc
退出)
Ctrl rEsc| Key | Action |
|---|---|
| Resize in direction |
| Increase in direction |
| Increase size |
| Decrease size |
| 按键 | 操作 |
|---|---|
| 向对应方向调整面板大小 |
| 向对应方向大幅调整面板大小 |
| 增大面板大小 |
| 减小面板大小 |
Move Mode (Ctrl m
to enter, Esc
to exit)
Ctrl mEsc移动面板模式(按Ctrl m
进入,Esc
退出)
Ctrl mEsc| Key | Action |
|---|---|
| Move pane in direction |
| 按键 | 操作 |
|---|---|
| 向对应方向移动面板 |
Scroll Mode (Ctrl b
to enter, Esc
to exit)
Ctrl bEsc滚动模式(按Ctrl b
进入,Esc
退出)
Ctrl bEsc| Key | Action |
|---|---|
| Scroll down/up |
| Half page down/up |
| Scroll to top |
| Scroll to bottom |
| 按键 | 操作 |
|---|---|
| 向下/向上滚动 |
| 向下/向上滚动半页 |
| 滚动到顶部 |
| 滚动到底部 |
Locked Mode (Ctrl g
to toggle)
Ctrl g锁定模式(按Ctrl g
切换)
Ctrl gAll keys pass through to the terminal. Only exits.
Ctrl g所有按键直接传递给终端。仅按可退出该模式。
Ctrl gModes NOT configured (from defaults)
未配置的默认模式
Your config does not define: , , , , , , . Consider adding and modes for search-in-scrollback and session manager access.
tabsearchentersearchrenametabrenamepanesessiontmuxsearchsession你的配置未定义以下模式:、、、、、、。建议添加和模式,以支持回滚搜索和会话管理功能。
tabsearchentersearchrenametabrenamepanesessiontmuxsearchsessionYour Config Summary
你的配置摘要
kdl
// Key settings in config.kdl:
default_layout "compact" // 1-line compact-bar (tab + status combined)
pane_frames false // No borders between panes
theme "default" // Base16 dark theme (defined inline)
default_shell "~/.nix-profile/bin/fish"
copy_on_select true
scrollback_editor "/usr/bin/nvim"
session_serialization true // Enable resurrection
serialize_pane_viewport true // Save visible content
max_panes 100
layout_dir "~/.config/zellij/layouts"Note: and use paths (Linux). On macOS these should be paths. Consider using or updating for cross-platform use.
default_shelllayout_dir/home/wcygan//Users/wcygan/$HOMEkdl
// config.kdl中的关键设置:
default_layout "compact" // 单行紧凑栏(标签页+状态栏合并)
pane_frames false // 面板之间无边框
theme "default" // Base16深色主题(内联定义)
default_shell "~/.nix-profile/bin/fish"
copy_on_select true
scrollback_editor "/usr/bin/nvim"
session_serialization true // 启用会话恢复功能
serialize_pane_viewport true // 保存面板可见内容
max_panes 100
layout_dir "~/.config/zellij/layouts"注意:和使用的是Linux路径。在macOS上应改为路径。建议使用以实现跨平台兼容。
default_shelllayout_dir/home/wcygan//Users/wcygan/$HOMEYour Layouts
你的布局文件
dev.kdl (3-tab development layout)
dev.kdl(3标签页开发布局)
Tab "main" (focused):
┌─────────────────────┬──────────┐
│ │ terminal │
│ editor (70%) ├──────────┤
│ │ logs │
└─────────────────────┴──────────┘
Tab "git": lazygit (full pane)
Tab "monitor": btop (50%) + services (50%)Load with: or
zellij -l devzellij --layout ~/.config/zellij/layouts/dev.kdl标签页 "main"(默认焦点):
┌─────────────────────┬──────────┐
│ │ terminal │
│ 编辑器(占70%) ├──────────┤
│ │ 日志面板 │
└─────────────────────┴──────────┘
标签页 "git": lazygit(全屏面板)
标签页 "monitor": btop(占50%)+ 服务面板(占50%)加载方式: 或
zellij -l devzellij --layout ~/.config/zellij/layouts/dev.kdlModes Reference (13 total)
模式参考(共13种)
| Mode | Purpose | Your binding |
|---|---|---|
| Default operations | (default) |
| Pass-through (safety) | |
| Pane management | |
| Resize panes | |
| Move panes | |
| Scroll buffer | |
| Tab management | (not bound) |
| Search in scrollback | (not bound) |
| Type search query | (not bound) |
| Rename a tab | (not bound) |
| Rename a pane | (not bound) |
| Session management | (not bound) |
| tmux compatibility | (not bound) |
| 模式 | 用途 | 你的快捷键绑定 |
|---|---|---|
| 默认操作模式 | (默认进入) |
| 按键直通模式(安全用途) | |
| 面板管理 | |
| 调整面板大小 | |
| 移动面板 | |
| 滚动缓冲区 | |
| 标签页管理 | (未绑定) |
| 回滚内容搜索 | (未绑定) |
| 输入搜索关键词 | (未绑定) |
| 重命名标签页 | (未绑定) |
| 重命名面板 | (未绑定) |
| 会话管理 | (未绑定) |
| Tmux兼容模式 | (未绑定) |
CLI Quick Reference
CLI 快速参考
Session Management
会话管理
bash
zellij # New session
zellij -s <name> # Named session
zellij ls # List all (running + exited)
zellij attach <name> # Attach / resurrect
zellij attach -c <name> # Create-or-attach
zellij kill-session <name> # Kill running session
zellij delete-session <name> # Delete exited session
zellij kill-all-sessions # Kill all
zellij delete-all-sessions # Delete all exitedbash
zellij # 新建会话
zellij -s <name> # 新建命名会话
zellij ls # 列出所有会话(运行中+已退出)
zellij attach <name> # 连接/恢复会话
zellij attach -c <name> # 连接或新建会话
zellij kill-session <name> # 终止运行中的会话
zellij delete-session <name> # 删除已退出的会话
zellij kill-all-sessions # 终止所有会话
zellij delete-all-sessions # 删除所有已退出的会话Run Commands in Panes
在面板中运行命令
bash
zellij run -- htop # New pane running htop
zellij run -f -- htop # Floating pane
zellij run -f --width 80% --height 80% -- htop # Sized floating
zellij run -i -- make build # In-place (replaces current pane)
zellij run -c -- make test # Close pane on exit
zellij run -s -- dangerous-cmd # Start suspended (ENTER to run)
zellij run -n "build" -- make # Named panebash
zellij run -- htop # 新建运行htop的面板
zellij run -f -- htop # 新建浮动面板运行htop
zellij run -f --width 80% --height 80% -- htop # 新建指定大小的浮动面板运行htop
zellij run -i -- make build # 在当前面板中运行(替换当前面板内容)
zellij run -c -- make test # 命令执行完成后自动关闭面板
zellij run -s -- dangerous-cmd # 新建暂停状态的面板(按ENTER后运行命令)
zellij run -n "build" -- make # 新建命名为“build”的面板Edit Files
编辑文件
bash
zellij edit src/main.rs # Open in $EDITOR pane
zellij edit -f src/main.rs # Floating editor pane
zellij edit -l 42 src/main.rs # Open at line 42bash
zellij edit src/main.rs # 在$EDITOR面板中打开文件
zellij edit -f src/main.rs # 在浮动编辑器面板中打开文件
zellij edit -l 42 src/main.rs # 打开文件并定位到第42行Actions (from outside or within)
操作命令(外部或内部执行)
bash
zellij action new-pane # New pane
zellij action new-pane --floating # New floating pane
zellij action new-tab --name "build" # Named new tab
zellij action go-to-tab 2 # Switch to tab 2
zellij action dump-layout # Export current layout to stdout
zellij action dump-screen /tmp/out.txt # Dump pane content
zellij action switch-mode locked # Enter locked mode
zellij action toggle-floating-panes # Toggle floats
zellij action rename-session "work" # Rename sessionbash
zellij action new-pane # 新建面板
zellij action new-pane --floating # 新建浮动面板
zellij action new-tab --name "build" # 新建命名为“build”的标签页
zellij action go-to-tab 2 # 切换到第2个标签页
zellij action dump-layout # 将当前布局导出到标准输出
zellij action dump-screen /tmp/out.txt # 导出面板内容到文件
zellij action switch-mode locked # 进入锁定模式
zellij action toggle-floating-panes # 切换浮动面板显示状态
zellij action rename-session "work" # 重命名会话Setup Utilities
设置工具
bash
zellij setup --dump-config # Print default config
zellij setup --dump-layout default # Print default layout
zellij setup --dump-layout compact # Print compact layout
zellij setup --dump-swap-layout default # Print swap layout
zellij setup --generate-completion fish # Fish completions
zellij setup --generate-auto-start fish # Auto-start script
zellij setup --check # Validate configbash
zellij setup --dump-config # 打印默认配置
zellij setup --dump-layout default # 打印默认布局
zellij setup --dump-layout compact # 打印紧凑布局
zellij setup --dump-swap-layout default # 打印交换布局
zellij setup --generate-completion fish # 生成Fish shell补全脚本
zellij setup --generate-auto-start fish # 生成自动启动脚本
zellij setup --check # 验证配置文件有效性Convenience Aliases (from shell completions)
便捷别名(来自shell补全)
| Alias | Expands to |
|---|---|
| |
| |
| |
| 别名 | 展开命令 |
|---|---|
| |
| |
| |
Session Resurrection
会话恢复
Your config has resurrection enabled (, ).
session_serialization trueserialize_pane_viewport trueWhat's saved: Layout, pane structure, commands, visible viewport, scrollback.
What's NOT saved: Running processes. Commands show "Press ENTER to run..." on resurrection.
bash
zellij ls # Shows EXITED sessions
zellij attach <exited-session> # Resurrect it
zellij attach <name> --force-run-commands # Skip ENTER confirmation
zellij delete-session <name> # Permanently removeSerialized sessions are human-readable KDL layout files in the cache directory. They can be shared, modified, or loaded directly with .
zellij --layout你的配置已启用会话恢复功能(,)。
session_serialization trueserialize_pane_viewport true保存的内容:布局、面板结构、命令、面板可见视口、回滚缓冲区。
不保存的内容:运行中的进程。恢复会话后,命令会显示“按ENTER键运行...”。
bash
zellij ls # 查看已退出的会话
zellij attach <exited-session> # 恢复已退出的会话
zellij attach <name> --force-run-commands # 跳过ENTER确认直接恢复运行命令
zellij delete-session <name> # 永久删除已退出的会话序列化的会话是缓存目录中的可读KDL布局文件。这些文件可以共享、修改,或通过直接加载。
zellij --layoutFloating & Stacked Panes
浮动与堆叠面板
Floating: then (toggle), (embed/float), or (if default binds)
Pinned floating: Always-on-top panes (pin via CLI: )
Stacked: Panes in a stack where only the focused one is expanded. Define in layouts with .
Ctrl pweAlt fzellij run -f --pinned -- cmdstacked=true浮动面板:按然后按(切换显示)、(切换嵌入/浮动),或使用默认快捷键(如果未修改默认绑定)
固定浮动面板:始终显示在顶层的面板(通过CLI创建:)
堆叠面板:仅当前焦点面板展开的堆叠式面板。在布局文件中通过定义。
Ctrl pweAlt fzellij run -f --pinned -- cmdstacked=truePlugins (Built-in)
内置插件
| Plugin | Location | Description |
|---|---|---|
| | Tab bar (1 line) |
| | Status bar with keybind hints (2 lines) |
| | Combined tab+status (1 line) |
| | File browser sidebar |
| | Session switcher + resurrection UI |
| | File picker (cwd based) |
| | Runtime config editor |
| | Plugin management UI |
Load in layouts:
kdl
pane size=1 borderless=true {
plugin location="zellij:compact-bar"
}| 插件 | 位置 | 描述 |
|---|---|---|
| | 标签页栏(单行) |
| | 带快捷键提示的状态栏(两行) |
| | 合并标签页+状态栏的紧凑栏(单行) |
| | 文件浏览器侧边栏 |
| | 会话切换器+恢复UI |
| | 基于当前目录的文件选择器 |
| | 运行时配置编辑器 |
| | 插件管理UI |
在布局文件中加载插件:
kdl
pane size=1 borderless=true {
plugin location="zellij:compact-bar"
}Troubleshooting
故障排查
| Issue | Fix |
|---|---|
| macOS Alt key not working | Configure in terminal app (iTerm2: Profiles → Keys → Left Option = Esc+) |
| Copy not working | Add |
| Font/character issues | Use Nerd Font or |
| Ctrl+H triggers Move mode | Terminal sends Ctrl+H as backspace — remap in terminal or Zellij |
| Nesting prevention | Check |
| Mouse selection | Hold SHIFT to bypass Zellij mouse capture |
| Styled underline colors wrong | Add |
| Config not loading | Check |
| 问题 | 解决方法 |
|---|---|
| macOS上Alt键无效 | 在终端应用中配置(iTerm2:配置文件 → 按键 → 左Option键 = Esc+) |
| 复制功能无效 | 在配置文件中添加 |
| 字体/字符显示异常 | 使用Nerd Font或设置 |
| Ctrl+H触发移动模式 | 终端将Ctrl+H识别为退格键 — 在终端或Zellij中重新映射快捷键 |
| 防止嵌套启动 | 启动前检查 |
| 鼠标选择 | 按住SHIFT键绕过Zellij的鼠标捕获 |
| 样式化下划线颜色错误 | 添加 |
| 配置文件未加载 | 运行 |
Fish Shell Integration
Fish Shell 集成
fish
undefinedfish
undefinedNesting prevention (add to config.fish or conf.d/)
防止嵌套启动(添加到config.fish或conf.d/目录下)
if status is-interactive; and not set -q ZELLIJ
zellij attach -c default
end
if status is-interactive; and not set -q ZELLIJ
zellij attach -c default
end
Generate completions
生成补全脚本
zellij setup --generate-completion fish > ~/.config/fish/completions/zellij.fish
undefinedzellij setup --generate-completion fish > ~/.config/fish/completions/zellij.fish
undefinedEnvironment Variables
环境变量
| Variable | Description |
|---|---|
| Set to |
| Current session name |
| Override config directory |
| Override config file |
| Auto-attach to existing session |
| Exit shell when Zellij exits |
| 变量 | 描述 |
|---|---|
| 在Zellij会话内会被设为 |
| 当前会话名称 |
| 覆盖默认配置目录 |
| 覆盖默认配置文件 |
| 自动连接到现有会话 |
| 当Zellij退出时自动关闭shell |
Layout Authoring Quick Reference
布局编写快速参考
kdl
layout {
// Tab template applied to all tabs
default_tab_template {
pane size=1 borderless=true { plugin location="zellij:tab-bar" }
children // ← where tab content goes
pane size=2 borderless=true { plugin location="zellij:status-bar" }
}
tab name="code" focus=true {
pane split_direction="vertical" {
pane size="60%" name="editor" edit="src/main.rs"
pane size="40%" split_direction="horizontal" {
pane name="term"
pane name="test" command="make" { args "test"; }
}
}
}
tab name="git" {
pane command="lazygit"
}
// Floating panes section
floating_panes {
pane x="10%" y="10%" width="80%" height="80%" name="scratch"
}
}kdl
layout {
// 应用于所有标签页的默认标签页模板
default_tab_template {
pane size=1 borderless=true { plugin location="zellij:tab-bar" }
children // ← 标签页内容的插入位置
pane size=2 borderless=true { plugin location="zellij:status-bar" }
}
tab name="code" focus=true {
pane split_direction="vertical" {
pane size="60%" name="editor" edit="src/main.rs"
pane size="40%" split_direction="horizontal" {
pane name="term"
pane name="test" command="make" { args "test"; }
}
}
}
tab name="git" {
pane command="lazygit"
}
// 浮动面板区域
floating_panes {
pane x="10%" y="10%" width="80%" height="80%" name="scratch"
}
}Key layout attributes
布局关键属性
| Attribute | Applies to | Values |
|---|---|---|
| pane | |
| pane | |
| pane | Command to execute |
| child of command pane | |
| pane | File path (opens in $EDITOR) |
| pane, tab, layout | Working directory |
| pane, tab | Display name |
| pane, tab | |
| pane | |
| pane | Close when command exits |
| pane | Wait for ENTER |
| pane | Stack children |
| child block | Plugin URL |
CWD composes: pane cwd → tab cwd → layout cwd → execution directory. Relative paths chain; absolute paths override.
For the full actions reference, theme system, swap layouts, and plugin configuration, see reference.md.
| 属性 | 适用对象 | 取值 |
|---|---|---|
| 面板 | |
| 面板 | |
| 面板 | 要执行的命令 |
| 命令面板的子属性 | |
| 面板 | 要打开的文件路径(在$EDITOR中打开) |
| 面板、标签页、布局 | 工作目录 |
| 面板、标签页 | 显示名称 |
| 面板、标签页 | |
| 面板 | |
| 面板 | 命令执行完成后自动关闭面板 |
| 面板 | 新建暂停状态的面板 |
| 面板 | 堆叠子面板 |
| 面板子块 | 插件URL |
工作目录优先级:面板cwd → 标签页cwd → 布局cwd → 执行Zellij时的目录。相对路径会继承,绝对路径会覆盖。
如需完整的操作参考、主题系统、交换布局和插件配置,请查看reference.md。