tmuxinator / zellij：每个项目一套预设的 terminal 布局

起因

打开项目 X 的工作流总是：开 tmux session → split 3 panel → 各跑
vim . / npm run dev / tail -f log。
切到项目 Y 又是另一套布局。每次手动布几次烦。

tmuxinator（YAML 定义 tmux layout）和 zellij（自带 layout 系统）
让"项目 → 预设布局" 一行命令搞定。

tmuxinator（tmux 上层）

gem install tmuxinator
# 或：brew install tmuxinator

tmuxinator new myapp
# 打开 YAML 编辑器

# ~/.config/tmuxinator/myapp.yml
name: myapp
root: ~/projects/myapp

windows:
  - editor:
      layout: main-vertical
      panes:
        - nvim .
        - git status
        - tail -f log/dev.log
  - server:
      panes:
        - npm run dev
        - npm run watch:css
  - db:
      panes:
        - psql -d myapp
  - shell:
      panes:
        - clear

启动：

tmuxinator start myapp
# 或 mux start myapp（短 alias）

自动：

开新 tmux session myapp
第 1 个 window 'editor'：左侧 nvim，右侧上 git status / 下 log tail
第 2 个 window 'server'：上下分 panel 跑 dev + watch
第 3 个 window 'db'：psql
第 4 个 window 'shell'：空 shell

切 window：tmux prefix + 数字键。整个项目立刻 ready。

高级：pre/post hook

pre: docker compose -f docker-compose.dev.yml up -d
post_window_create: sleep 1

windows:
  - editor:
      panes:
        - nvim .

pre 在启动 tmux 前跑（启 DB / 装依赖）。post_window_create 每个
window 创建后 sleep。

多 session 同时

tmuxinator start myapp
# tmux session "myapp" 起来

tmuxinator start client-x   # 另一个项目
# tmux session "client-x" 同时存在

tmux ls 看所有 session；tmux a -t myapp 进任意一个。

zellij（tmux 替代品，layout 内置）

brew install zellij
cargo install zellij

zellij --layout default
# 默认 layout 启动

zellij 跟 tmux 比：

modern UI（status bar + tips 自动显示）
鼠标支持开箱即用
layout 是 KDL 格式（更结构化）
内置插件系统（Wasm）
性能（Rust）

KDL layout

~/.config/zellij/layouts/myapp.kdl：

layout {
    cwd "/Users/me/projects/myapp"

    tab name="editor" focus=true {
        pane command="nvim" {
            args "."
        }
        pane split_direction="vertical" size="40%" {
            pane command="git" { args "status" }
            pane command="bash" { args "-c" "tail -f log/dev.log" }
        }
    }

    tab name="server" {
        pane command="npm" { args "run" "dev" }
        pane command="npm" { args "run" "watch:css" }
    }

    tab name="db" {
        pane command="psql" { args "-d" "myapp" }
    }
}

启动：

zellij --layout myapp
# 或：
zellij -s myapp -l myapp

-s myapp session 名；-l myapp 用这个 layout。

resurrect (持久化)

zellij list-sessions
zellij attach myapp
# attach 重连，状态保留

zellij kill-session myapp

机器重启后 session 消失（跟 tmux 一样）。
需要持久化用 tmux + tmux-resurrect 插件。

我用的 workflow

混用：

daily 默认 shell 用 tmux + tmuxinator（成熟、稳）
新项目尝试 zellij（更好看 / 鼠标好）

每个项目根目录有 .tmuxinator.yml：

cd myapp
mux .            # 在当前目录跑 tmuxinator 配置

或者 cd 时自动启 tmux：

# ~/.zshrc
function cd() {
  builtin cd "$@"
  if [[ -f .tmuxinator.yml && -z "$TMUX" ]]; then
    local name=$(basename "$PWD")
    tmuxinator start "$name" -f .tmuxinator.yml -n "$name" 2>/dev/null
  fi
}

cd 进项目自动开预设布局。

与 IDE 的关系

VSCode 已经能 multi-panel + integrated terminal。
为什么还要 tmux/zellij？

远程开发：SSH 上 tmux session 断线不丢
CLI 主导：vim/neovim/helix 用户原生体验
多 session：可以跑跑 backend / frontend / docs 各一个 tmux
互不干扰
持久 background：长跑任务用 tmux 后台跑，不占 IDE

IDE 用户也常用 tmux 跑 background server，VSCode 只 edit + git。

团队共享 layout

.tmuxinator.yml 进 git → 团队成员 mux . 起来同样 layout。
对 onboarding 价值极大：新人不需要"我应该开哪几个 terminal"。

注意：layout 文件里硬编码用户 path（/home/me/...）要避免，
用 ${PWD} 或 . 相对路径。

效果

项目切换从"开 5 个 terminal 各布置 1 分钟" → 1 秒
远程 SSH 断线后 reattach 看到所有状态保留
团队新人 onboarding 直接 mux . 起来全套
一台机器 daily 同时挂 4-5 个项目 session，按需 attach 切换

踩过的坑

tmuxinator 不更新某个 pane 命令：YAML 改了但 session 已经
起来 → 改动不生效。tmuxinator kill myapp 再 start。
windows 排序：YAML 列出顺序就是 tab 顺序。习惯把 editor 放第 1（默认 attach 进的）。
session 同名只能一个：第二次 start 提示已存在。mux start myapp
会 attach 已有的（feature）；要重启加 --no-attach + kill 旧的。
layout 文件 path 跨机器不一致：用 ~/projects/... 不要硬
/home/specific-user/。
tmux 自动 attach 把别人踢出去：多人共享 server 上同一 tmux
不友好。建议 tmux a -t myapp -d (-d detach 别人) 或者 read-only
attach（-r）。