WezTerm 实战：从单窗格到远程会话的 4 段配置

WezTerm 实战：从单窗格到远程会话的 4 段配置

【免费下载链接】weztermA GPU-accelerated cross-platform terminal emulator and multiplexer written by @wez and implemented in Rust项目地址: https://gitcode.com/GitHub_Trending/we/wezterm

深夜构建跑在远端机器上，本地在 tail 日志，手边还想调出编辑器看 diff——一个终端窗口显然不够用。WezTerm 是一个用 Rust 编写的 GPU 加速跨平台终端多路复用器，把分屏、快捷键和远程连接都交给一份 WezTerm Lua 配置来管，这份配置就是本文的主角。

机制速览：一个 Lua 文件如何驱动整个终端

窗口、渲染与会话持久化都由~/.wezterm.lua驱动：启动时读取配置，GPU 负责渲染，多路复用守护进程接管后，窗格在窗口关闭后依然常驻。四个场景改的都是同一份文件，不存在分散的状态。

场景实战：四段递进配置

3 分钟搭好分屏工作台

看代码、tail 日志、翻历史输出要来回切窗口，这是日常开发里最高频的浪费，分屏加一套 Leader 键就能把它压掉。

local wezterm = require 'wezterm' local config = wezterm.config_builder() -- CTRL+a 作 leader 前缀：不与 shell 原生快捷键打架 config.leader = { key = 'a', mods = 'CTRL', timeout_milliseconds = 2000 } config.keys = { { key = '|', mods = 'LEADER|SHIFT', action = wezterm.action.SplitHorizontal { domain = 'CurrentPaneDomain' } }, { key = 'h', mods = 'LEADER', action = wezterm.action.ActivatePaneDirection 'Left' }, { key = 'l', mods = 'LEADER', action = wezterm.action.ActivatePaneDirection 'Right' }, } config.scrollback_lines = 50000 -- 留 5 万行历史，tail 日志不被截断 return config

从此 Ctrl+a 再按 | 水平分屏、h/l 左右换窗格，这一套能省掉每天十几次鼠标点击。SplitHorizontal的domain指定在哪个域里开新窗格，CurrentPaneDomain保证不会误伤旁边正在跑的会话。

多项目并行：标签栏、启动菜单与状态栏

前端仓库、后端仓库和监控日志同时开着，标签页越堆越乱，哪个是哪个全凭记忆。

-- 标签栏放底部+显示序号：标签越多，靠序号点得越准 config.tab_bar_at_bottom = true config.show_tab_index_in_tab_bar = true -- launch_menu：右键菜单里直接生成预设会话，省去每次敲 cd config.launch_menu = { { label = '后端仓库', args = { 'bash', '-c', 'cd ~/code/backend && exec bash' } }, { label = '监控日志', args = { 'bash', '-c', 'tail -F /var/log/app.log' } }, } -- 状态栏显示当前窗格工作目录，一眼看清自己在哪个仓库 wezterm.on('update-status', function(window, pane) window:set_right_status(wezterm.format({ { Foreground = { Color = '#f5f5f5' } }, { Text = ' ' .. pane.foreground_cwd .. ' ' }, })) end)

现在每个标签页都知道自己是谁，最常用的两个入口不需要再敲命令。

远程运维：SSH 域与断网不死的会话

运维机上网络抖一下，远端会话就没了——根因是远端只跑了一个 shell，而不是复用器。

-- ssh_domains：配置里声明远端机器，之后只需 wezterm ssh prod config.ssh_domains = { { name = 'prod', user = 'deploy', host = '10.0.0.9' }, } -- 两个习惯： -- 1) 远端装有 wezterm mux 服务后，断网会话依然常驻 -- 2) 本地用 wezterm cli list 确认哪些会话还活着

不显式声明域也可以，WezTerm 会自动解析~/.ssh/config里的 Host 条目，声明只是让名字更可控。之后wezterm ssh prod进入的就是远端常驻会话，本地窗口关了窗格也不死，这才是「多路复用器」该有的分量。

跨平台：一份配置伺候三台机器

同一份配置在 Windows 上黑屏、在 macOS 上显得寡淡，解法是按平台分支，而不是维护三份文件。

local t = wezterm.target_triple -- 标识当前平台，一份配置三种观感 if t:find('windows') then config.front_end = 'OpenGL' -- Windows 上 OpenGL 管线更稳 elseif t:find('apple') then config.macos_window_background_blur = 20 -- 原生高斯模糊比纯透明更耐看 config.window_background_opacity = 0.92 else config.enable_wayland = true -- Linux 优先 Wayland，规避输入抖动 end

三台机器共用一份文件、只有外观分叉，维护成本直接归零。

可复用技巧：四条不挑场景的配置经验

• Leader 键设计：修饰键+单字符做前缀，宽限窗口给足 2000ms；避开 shell 历史扩展会争抢的字符。
• 字体回退顺序：编程字体放第一位，CJK 和 emoji 字体压轴，wezterm.font_with_fallback一行解决方框和连字。
• 回滚阈值：日常 1 万行够用，长日志 tail 给 5 万；再往上只是吃内存，屏幕也渲染不到。
• 帧率与透明度：max_fps封顶 60 保帧率，window_background_opacity低于 0.9 时务必配浅底主题，否则文字发虚。

排错速查：四个高频现象与一行修复

• 改完配置新窗口还是老样子→ Lua 语法错误静默回退到默认配置 → 终端里跑wezterm start看报错输出。
• 终端里中文渲染成方框→ 等宽字体不含 CJK 字形且未设回退 → 在wezterm.font_with_fallback({ ... })里补一个中文字体。
• Leader 后的第二键不生效→ 宽限窗口太短或组合被系统占用 →timeout_milliseconds加到 2000，或换个少用字符。
• 远端会话一断网就没了→ 远端只跑 shell 没跑复用器 → 远端装上 mux 服务，再用wezterm ssh <域>重连。

收束：从配置文件到工作流

四段配置搭起来的不只是更好看的终端，而是一套跨本地与远端、窗口关了也不丢状态的常驻工作区。想继续深挖：多路复用文档讲清了会话管理与 tmux 互操作的完整语义，全部配置字段的清单在 config/src/config.rs。

【免费下载链接】weztermA GPU-accelerated cross-platform terminal emulator and multiplexer written by @wez and implemented in Rust项目地址: https://gitcode.com/GitHub_Trending/we/wezterm