tmux

tmux & tmuxp 技能

通过 tmuxp YAML 配置创建、编辑、调试和优化 tmux 会话。

快速决策

任务	方法
新建项目工作区	根据模板创建 tmuxp YAML
修复会话加载错误	检查 session_name、YAML 语法和工具可用性
多环境 K8s	使用环境变量和按环境划分的窗口，并设置安全防护
简单开发环境	2-3 个窗口：编辑器、服务端、终端
复杂基础设施	before_script 校验 + 辅助脚本 + 监控窗口
捕获现有布局	执行 tmuxp freeze，然后清理输出

会话名称规则

tmux 会话名称不能包含句点（.）或冒号（:）。

常见陷阱：当用户名包含句点（例如 first.last）时，在 session_name 中使用 ${USER}。请始终使用静态名称或进行清理：

# BAD - breaks if USER contains periods
session_name: ${USER}-project

# GOOD - static name
session_name: project-dev

# GOOD - sanitized
session_name: project-${USER//\./-}

配置结构

session_name: project-name          # Required. No periods or colons.
start_directory: ~/Projects/foo     # Default working dir for all windows
environment:                        # Session-wide env vars
  PROJECT_ROOT: ~/Projects/foo
suppress_history: false             # Whether to hide commands from shell history

before_script: |                    # Runs before session creation. Exit 1 = abort.
  echo "Validating..."

after_script: |                     # Runs after session is destroyed
  echo "Cleaning up..."

windows:
  - window_name: editor             # Window identifier
    focus: true                     # Make this the active window on load
    layout: main-vertical           # Pane layout
    start_directory: ~/Projects/foo/src
    options:
      main-pane-width: 70%          # Layout-specific options
    shell_command_before:            # Runs in ALL panes before pane commands
      - source ~/.zshrc
    panes:
      - focus: true                 # Active pane within window
        shell_command:
          - vim .
      - shell_command:
          - npm test -- --watch

布局

布局	用途	窗格排列
main-vertical	编辑器 + 侧边栏	左侧较大，右侧纵向堆叠
main-horizontal	日志 + 状态	顶部较大，底部拆分
even-horizontal	并排均分	水平均分
even-vertical	纵向均分	纵向均分
tiled	监控仪表板	均分网格窗格

通过选项控制主窗格大小：

options:
  main-pane-width: 70%    # For main-vertical
  main-pane-height: 65%   # For main-horizontal

从运行中的会话捕获自定义布局：

tmux display-message -p '#{window_layout}'
# Returns: "bb62,159x48,0,0{79x48,0,0,79x48,80,0}"

窗格定义

panes:
  # Simple command
  - vim README.md

  # Multiple commands
  - shell_command:
      - cd ~/project
      - source .venv/bin/activate
      - python app.py

  # Empty pane
  - null     # or: blank, pane

  # With focus
  - focus: true
    shell_command:
      - k9s

环境变量

environment:
  # Static values
  PROJECT_NAME: my-app

  # Reference existing vars (expanded at load time)
  HOME_DIR: ${HOME}

  # Multi-environment pattern
  K8S_CTX_DEV: aks-myapp-dev
  K8S_CTX_STG: aks-myapp-stg
  K8S_CTX_PRD: aks-myapp-prd

  # Defaults
  EDITOR: ${EDITOR:-vim}

切勿将机密信息硬编码。从 shell 引用环境变量：${AZURE_SUBSCRIPTION_ID}。

before_script 校验

使用 before_script 校验前置条件。退出码为 1 时会中止会话创建：

before_script: |
  # Check project exists
  [ -d "$PROJECT_ROOT" ] || { echo "Project not found"; exit 1; }

  # Check required tools
  for tool in kubectl terraform docker; do
    command -v $tool >/dev/null || echo "Warning: $tool not found"
  done

  # Check connectivity
  kubectl cluster-info >/dev/null 2>&1 || echo "Warning: Cannot reach cluster"

生产环境安全模式

通过只读访问和警告保护生产环境：

- window_name: k8s-prod
  panes:
    - shell_command:
        - echo "PRODUCTION - READ-ONLY ACCESS"
        - echo "DO NOT use: apply, delete, edit, patch"
        - kubectl config use-context $K8S_CTX_PRD
        - k9s --readonly

CLI 命令

tmuxp load config-name          # Load from ~/.tmuxp/
tmuxp load ./path/to/file.yaml  # Load from path
tmuxp load -y config-name       # Skip confirmation prompt
tmuxp load -d config-name       # Load detached (background)
tmuxp ls                        # List available configs
tmuxp freeze session-name       # Capture running session to YAML
tmuxp convert file.json         # Convert JSON config to YAML
tmuxp edit config-name          # Edit config in $EDITOR
tmuxp debug-info                # Show environment info

故障排查

错误	原因	修复方法
BadSessionName: contains periods	session_name 中有 .（通常来自 ${USER}）	移除 ${USER} 前缀或进行清理
BadSessionName: contains colons	session_name 中有 :	从名称中移除冒号
会话已存在	session_name 重复	结束旧会话：tmux kill-session -t name
命令未执行	shell 兼容性	先手动测试命令
布局异常	终端太小，无法容纳该布局	使用预定义布局，或通过 tmuxp load -d 测试
环境变量未展开	语法错误	在 YAML 值中使用 ${VAR}，而不是 $VAR

调试：运行 tmuxp -v load config.yaml 获取详细输出。

参考资料

• WORKFLOWS.md - 常见工作流模式（开发、基础设施、监控）
• BEST-PRACTICES.md - 生产环境模式、安全性和组织方式
• templates/ - 可直接使用的配置模板

工作流：创建新配置

1. 确定项目类型（开发、基础设施、监控、混合）
2. 从 templates/ 中选择模板
3. 设置 session_name（不含句点或冒号）、start_directory 和环境变量
4. 按功能设计窗口（编辑器、服务端、日志、k8s 等）
5. 选择符合各窗口用途的布局
6. 如果项目有外部依赖，添加 before_script 校验
7. 为任何可访问生产环境的窗口添加安全防护
8. 测试：运行 tmuxp load -d config.yaml，然后执行 tmux attach -t session-name

---

注意事项

• 会话名称包含句点会导致 Unix 套接字路径出错： ${USER} 包含 .（例如 first.last）时，会触发 BadSessionName，因为 tmux 会将名称用于 /tmp/tmux-UID/ 套接字路径。请使用固定名称，或通过 ${USER//\./-} 清理名称。
• before_script 会在全新的 shell 中运行，而不是在交互式 zsh 中运行： 别名、函数和从 .zshrc 加载的环境变量都不可用。command -v 可以使用，但 myalias 不行。如果依赖这些内容，请显式加载 ~/.zshrc。
• shell_command_before 会在窗口的每个窗格中运行： 耗时较长的命令（加载耗时 500ms 以上的 zsh 配置、激活虚拟环境）会累积延迟——包含 4 个窗格的窗口会让会话加载时间增加约 2s。如果只有一个窗格需要执行这些命令，请改用该窗格的 shell_command。
• tmuxp freeze 捕获的是实时状态，而非预期配置： 输出包含随机工作目录、经过历史记录展开的命令，以及具体的窗格尺寸——提交前请检查并清理。冻结生成的 YAML 只是起点，并非最终配置。
• 环境变量会在加载 YAML 时展开，而不是在启动窗格时展开： environment: FOO: ${BAR} 会从调用 tmuxp load 的 shell 中解析 $BAR。如果此时 $BAR 未设置，即使之后的窗格定义了它，它仍会保持为空。
• 多个窗格设置 focus: true 时，只会静默选中最后一个： 不会报错，也不会警告——文件只是在运行时看起来配置有误。开始调试前，请按窗口运行 grep -c "focus: true" 进行验证。