WezTerm 完整配置教程从跑通到个性化多窗格终端【免费下载链接】weztermA GPU-accelerated cross-platform terminal emulator and multiplexer written by wez and implemented in Rust项目地址: https://gitcode.com/GitHub_Trending/we/wezterm凌晨两点你的 SSH 会话断了终端里跑了两个小时的调试进程跟着一起没了。你希望它断线不丢现场、左边跑服务右边看日志还希望字体配色看着不累——这其实就是 WezTerm 这类 GPU 加速终端模拟器兼多路复用器terminal emulator and multiplexer要解决的三件事。本文带你用 Lua 配置文件把它从零调教成顺手工具。30 秒认识 WezTerm一句话定位WezTerm 是用 Rust 写的跨平台终端内置 tmux 式的窗格/标签管理渲染走 GPU。打个比方普通终端像一块只能整屏刷新的白板WezTerm 则像浏览器——窗口、标签、分屏都是它内部自己管理的页面GPU 只负责把变化区域合成到屏幕上所以拖动、缩放、滚回几千行历史都很跟手。它还有第二个身份mux 服务器模式让会话跑在常驻进程里客户端断了重连即可这就是SSH 断线不丢现场的底子。三步跑起来第一步装一个二进制即可不需要源码。以 Ubuntu/Debian 为例其他平台见 docs/install/linux.mdsudo apt install wezterm # 走官方 APT 源详见 docs/install/linux.md wezterm # 直接启动第二步在用户主目录放一个配置文件。官方推荐路径是~/.wezterm.luaWindows 为%USERPROFILE%\.wezterm.lualocal wezterm require wezterm local config wezterm.config_builder() config.initial_cols 120 -- 新窗口初始宽度默认 80 偏窄 config.initial_rows 28 config.font_size 13 config.color_scheme AdventureTime return config第三步验证生效保存文件后 WezTerm 会自动监听并重载配置窗口会立刻变成 120 列的新配色也可以按CTRLSHIFTR强制重载。配置文件的查找顺序不止主目录一条路完整决策流程--config参数 →$WEZTERM_CONFIG_FILE→ XDG 路径 → 主目录见 docs/config/files.md。场景一多窗格协作开发如何用 Leader 键管分屏场景左边跑测试、右边 tail 日志、下面再开一个 REPL反复用鼠标点窗格切焦点很打断节奏。为什么这样配WezTerm 支持类似 Vim 的 Leader 键——先按CTRLA进入前缀状态持续 1 秒再按一个字母执行动作。手指不用离开主键盘区比记CTRLSHIFT...组合键省力。在配置里加这段-- Leader 键CTRLA 作为前缀 config.leader { key a, mods CTRL, timeout_milliseconds 1000 } config.keys { { key %, mods LEADER, action wezterm.action.SplitHorizontal { domain CurrentPaneDomain } }, -- 左右分屏 { key _, mods LEADER, action wezterm.action.SplitVertical { domain CurrentPaneDomain } }, -- 上下分屏 { key h, mods LEADER, action wezterm.action.ActivatePaneDirection Left }, { key l, mods LEADER, action wezterm.action.ActivatePaneDirection Right }, { key j, mods LEADER, action wezterm.action.ActivatePaneDirection Down }, { key k, mods LEADER, action wezterm.action.ActivatePaneDirection Up }, }预期效果CTRLA然后%立刻把当前窗格从中间劈成左右两块CTRLA h/l/j/k像 Vim 一样四方向移动焦点。默认标签页界面长这样如果窗格太多记不住位置还有内置的 pane select 模式——按CTRLSHIFTA会列出所有窗格字母直达见 docs/quickselect.md 相关文档场景二个性化外观字体回退与半透明背景场景默认字体遇到 Nerd Font 图标分支符号、电源符号会显示豆腐块长时间盯着纯黑窗口又觉得累。为什么这样配WezTerm 内置了 JetBrains Mono、Noto Color Emoji 等字体见 assets/fonts/但补齐图标最稳的做法是显式声明回退链——主字体优先缺字再往下找。透明度则分两层window_background_opacity控制窗口底色、text_background_opacity控制文字区底色都可以独立调。config.font wezterm.font_with_fallback({ JetBrains Mono, SymbolsNerdFontMono, -- 补齐 Nerd Font 图标 Noto Color Emoji, -- 彩色 emoji }) config.font_size 13.0 config.window_background_opacity 0.92 -- 窗口底色留 8% 透明 config.text_background_opacity 0.90macOS 用户还可以再叠一层毛玻璃macos_window_background_blur是模糊强度0 为关闭if wezterm.target_triple:find(apple) then config.window_background_opacity 0.92 config.macos_window_background_blur 20 end预期效果git 分支图标、emoji 正常渲染桌面壁纸透过窗口微微可见。macOS 上的效果如下配色方案不用手搓十六进制内置了几十套config.color_scheme Catppuccin Mocha一行换肤可选项清单见 docs/config/lua/config/color_schemes.md。场景三换台电脑重连工作状态如何保留场景远程机上的开发会话笔记本合盖一晚上再打开希望进程还在、输出都在。为什么这样配两件事配合。一是把 scrollback 调大默认 10000 行长构建日志可能不够二是用 mux 会话模式——窗格挂在常驻的 mux 服务器上客户端只是显示器重连即还原现场。config.scrollback_lines 50000 -- 回滚历史按需给大 -- 指定默认工作区重连后回到固定的项目布局 config.default_workspace devwezterm connect # 以客户端模式连到本机 mux 服务器预期效果关闭窗口再wezterm connect之前的窗格、标签、输出都还在。命令行子命令全量列表可用wezterm cli查看说明文档在 docs/cli/general.md。场景四跨平台部署一份配置适配三个系统场景同一份配置在 macOS、Linux、Windows 上跑各自的默认 shell 和桌面行为不一样。为什么这样配wezterm.target_triple能拿到当前平台标识default_prog决定新窗格启动什么程序launch_menu是右键标签栏时的启动菜单。Linux 侧还需注意 Wayland 是默认禁用的想上 Wayland 要显式打开。if wezterm.target_triple:find(windows) then config.default_prog { pwsh, -NoLogo } elseif wezterm.target_triple:find(apple) then config.default_prog { zsh, -l } else config.enable_wayland true -- Linux启用 Wayland 支持 config.default_prog { bash, --login } end预期效果每个平台启动即打开习惯的 shell无需每次手动输入。窗口渲染引擎也可按机器能力选config.front_end支持OpenGL默认、WebGpu、Software三档老显卡上切到Software能绕过驱动问题。进阶玩法挑三个真正常用的1. 自定义状态栏。每 1 秒刷新一次当前目录和时间原理是监听update-status事件在事件回调里写window:set_right_statusconfig.status_update_interval 1000 -- 刷新间隔毫秒 wezterm.on(update-status, function(window, pane) local date wezterm.strftime(%H:%M:%S) window:set_right_status(wezterm.format({ { Foreground { Color #ffffff } }, { Background { Color #333333 } }, { Text .. date .. }, })) end)窗口右下角会多出一块实时时钟随时确认会话还活着。2. 命令面板。默认CTRLSHIFTP打开输入 split、send 等关键字即可检索所有操作等价于把整个快捷键表做成了可搜索菜单3. 配置拆模块。配置越长越难维护官方推荐把片段抽成 Lua 模块放到~/.config/wezterm/主配置require后调用apply_to_config(config)完整写法见 docs/config/files.md 的 Making your own Lua Modules 一节。这样配色、键位各占一个文件git 管理起来很清爽。踩坑指南现象改了配置没反应还是老样子原因配置语法错误时WezTerm 会显示错误并回退到内置默认配置而不是报错退出。 解法看启动时的错误提示也可用wezterm --config font_size20这类命令行覆盖快速确认程序本身正常。现象Leader 键按了没反应或正常输入被吞原因Leader 是模态前缀timeout_milliseconds内没按第二个键会超时退出且只有声明为mods LEADER的键才走这套逻辑。 解法检查 key 表里是否漏写LEADER确认config.leader与快捷键在同一份配置里生效。现象Nerd Font 图标显示为空心方块原因主字体里没有该字形且没有声明回退。 解法用wezterm.font_with_fallback挂上SymbolsNerdFontMonoArch 用户记得装ttf-nerd-fonts-symbols-mono。现象Linux 上窗口无法拖动/透明不生效原因Wayland 下window_background_opacity依赖合成器支持部分合成器会忽略它。 解法先回 X11 验证效果再换支持背景效果的合成器KDE 有专门支持效果参考 docs/screenshots/wezterm-kde-background-blur.png。现象Flatpak 里wezterm cli连不上、查不到窗格目录原因沙箱隔离跨进程信息受限官方文档明确建议重度用户转原生包。 解法按 docs/install/linux.md 换 APT/Copr/AppImage 等原生安装方式。排障路径汇总速查与下一步关键配置速查字段名与源码定义一致见 config/src/config.rs配置项作用常见取值initial_cols/initial_rows新窗口初始尺寸120 / 28font_size/font字号 / 字体回退链13 /font_with_fallback({...})color_scheme内置配色Catppuccin Mocha 等leader前缀键{ keya, modsCTRL, timeout_milliseconds1000 }scrollback_lines回滚行数10000window_background_opacity窗口底色透明度0~11 为不透明enable_waylandWayland 支持truefront_end渲染引擎OpenGL / WebGpu / Softwaredefault_workspace默认工作区字符串名常用快捷键CTRLSHIFTR重载配置、CTRLSHIFTP命令面板、CTRLSHIFTA窗格选择器、Leader 后%/ _ / hjkl分屏与导航。下一步建议把本文的键位和配色片段合并进~/.wezterm.lua用wezterm cli list感受一下 mux 会话挑一个 docs/recipes/workspaces.md 里的多工作区例子复刻到本机配置进 git 仓库——它只是 Lua 文件天然适合版本管理。【免费下载链接】weztermA GPU-accelerated cross-platform terminal emulator and multiplexer written by wez and implemented in Rust项目地址: https://gitcode.com/GitHub_Trending/we/wezterm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
WezTerm 完整配置教程从跑通到个性化多窗格终端【免费下载链接】weztermA GPU-accelerated cross-platform terminal emulator and multiplexer written by wez and implemented in Rust项目地址: https://gitcode.com/GitHub_Trending/we/wezterm凌晨两点你的 SSH 会话断了终端里跑了两个小时的调试进程跟着一起没了。你希望它断线不丢现场、左边跑服务右边看日志还希望字体配色看着不累——这其实就是 WezTerm 这类 GPU 加速终端模拟器兼多路复用器terminal emulator and multiplexer要解决的三件事。本文带你用 Lua 配置文件把它从零调教成顺手工具。30 秒认识 WezTerm一句话定位WezTerm 是用 Rust 写的跨平台终端内置 tmux 式的窗格/标签管理渲染走 GPU。打个比方普通终端像一块只能整屏刷新的白板WezTerm 则像浏览器——窗口、标签、分屏都是它内部自己管理的页面GPU 只负责把变化区域合成到屏幕上所以拖动、缩放、滚回几千行历史都很跟手。它还有第二个身份mux 服务器模式让会话跑在常驻进程里客户端断了重连即可这就是SSH 断线不丢现场的底子。三步跑起来第一步装一个二进制即可不需要源码。以 Ubuntu/Debian 为例其他平台见 docs/install/linux.mdsudo apt install wezterm # 走官方 APT 源详见 docs/install/linux.md wezterm # 直接启动第二步在用户主目录放一个配置文件。官方推荐路径是~/.wezterm.luaWindows 为%USERPROFILE%\.wezterm.lualocal wezterm require wezterm local config wezterm.config_builder() config.initial_cols 120 -- 新窗口初始宽度默认 80 偏窄 config.initial_rows 28 config.font_size 13 config.color_scheme AdventureTime return config第三步验证生效保存文件后 WezTerm 会自动监听并重载配置窗口会立刻变成 120 列的新配色也可以按CTRLSHIFTR强制重载。配置文件的查找顺序不止主目录一条路完整决策流程--config参数 →$WEZTERM_CONFIG_FILE→ XDG 路径 → 主目录见 docs/config/files.md。场景一多窗格协作开发如何用 Leader 键管分屏场景左边跑测试、右边 tail 日志、下面再开一个 REPL反复用鼠标点窗格切焦点很打断节奏。为什么这样配WezTerm 支持类似 Vim 的 Leader 键——先按CTRLA进入前缀状态持续 1 秒再按一个字母执行动作。手指不用离开主键盘区比记CTRLSHIFT...组合键省力。在配置里加这段-- Leader 键CTRLA 作为前缀 config.leader { key a, mods CTRL, timeout_milliseconds 1000 } config.keys { { key %, mods LEADER, action wezterm.action.SplitHorizontal { domain CurrentPaneDomain } }, -- 左右分屏 { key _, mods LEADER, action wezterm.action.SplitVertical { domain CurrentPaneDomain } }, -- 上下分屏 { key h, mods LEADER, action wezterm.action.ActivatePaneDirection Left }, { key l, mods LEADER, action wezterm.action.ActivatePaneDirection Right }, { key j, mods LEADER, action wezterm.action.ActivatePaneDirection Down }, { key k, mods LEADER, action wezterm.action.ActivatePaneDirection Up }, }预期效果CTRLA然后%立刻把当前窗格从中间劈成左右两块CTRLA h/l/j/k像 Vim 一样四方向移动焦点。默认标签页界面长这样如果窗格太多记不住位置还有内置的 pane select 模式——按CTRLSHIFTA会列出所有窗格字母直达见 docs/quickselect.md 相关文档场景二个性化外观字体回退与半透明背景场景默认字体遇到 Nerd Font 图标分支符号、电源符号会显示豆腐块长时间盯着纯黑窗口又觉得累。为什么这样配WezTerm 内置了 JetBrains Mono、Noto Color Emoji 等字体见 assets/fonts/但补齐图标最稳的做法是显式声明回退链——主字体优先缺字再往下找。透明度则分两层window_background_opacity控制窗口底色、text_background_opacity控制文字区底色都可以独立调。config.font wezterm.font_with_fallback({ JetBrains Mono, SymbolsNerdFontMono, -- 补齐 Nerd Font 图标 Noto Color Emoji, -- 彩色 emoji }) config.font_size 13.0 config.window_background_opacity 0.92 -- 窗口底色留 8% 透明 config.text_background_opacity 0.90macOS 用户还可以再叠一层毛玻璃macos_window_background_blur是模糊强度0 为关闭if wezterm.target_triple:find(apple) then config.window_background_opacity 0.92 config.macos_window_background_blur 20 end预期效果git 分支图标、emoji 正常渲染桌面壁纸透过窗口微微可见。macOS 上的效果如下配色方案不用手搓十六进制内置了几十套config.color_scheme Catppuccin Mocha一行换肤可选项清单见 docs/config/lua/config/color_schemes.md。场景三换台电脑重连工作状态如何保留场景远程机上的开发会话笔记本合盖一晚上再打开希望进程还在、输出都在。为什么这样配两件事配合。一是把 scrollback 调大默认 10000 行长构建日志可能不够二是用 mux 会话模式——窗格挂在常驻的 mux 服务器上客户端只是显示器重连即还原现场。config.scrollback_lines 50000 -- 回滚历史按需给大 -- 指定默认工作区重连后回到固定的项目布局 config.default_workspace devwezterm connect # 以客户端模式连到本机 mux 服务器预期效果关闭窗口再wezterm connect之前的窗格、标签、输出都还在。命令行子命令全量列表可用wezterm cli查看说明文档在 docs/cli/general.md。场景四跨平台部署一份配置适配三个系统场景同一份配置在 macOS、Linux、Windows 上跑各自的默认 shell 和桌面行为不一样。为什么这样配wezterm.target_triple能拿到当前平台标识default_prog决定新窗格启动什么程序launch_menu是右键标签栏时的启动菜单。Linux 侧还需注意 Wayland 是默认禁用的想上 Wayland 要显式打开。if wezterm.target_triple:find(windows) then config.default_prog { pwsh, -NoLogo } elseif wezterm.target_triple:find(apple) then config.default_prog { zsh, -l } else config.enable_wayland true -- Linux启用 Wayland 支持 config.default_prog { bash, --login } end预期效果每个平台启动即打开习惯的 shell无需每次手动输入。窗口渲染引擎也可按机器能力选config.front_end支持OpenGL默认、WebGpu、Software三档老显卡上切到Software能绕过驱动问题。进阶玩法挑三个真正常用的1. 自定义状态栏。每 1 秒刷新一次当前目录和时间原理是监听update-status事件在事件回调里写window:set_right_statusconfig.status_update_interval 1000 -- 刷新间隔毫秒 wezterm.on(update-status, function(window, pane) local date wezterm.strftime(%H:%M:%S) window:set_right_status(wezterm.format({ { Foreground { Color #ffffff } }, { Background { Color #333333 } }, { Text .. date .. }, })) end)窗口右下角会多出一块实时时钟随时确认会话还活着。2. 命令面板。默认CTRLSHIFTP打开输入 split、send 等关键字即可检索所有操作等价于把整个快捷键表做成了可搜索菜单3. 配置拆模块。配置越长越难维护官方推荐把片段抽成 Lua 模块放到~/.config/wezterm/主配置require后调用apply_to_config(config)完整写法见 docs/config/files.md 的 Making your own Lua Modules 一节。这样配色、键位各占一个文件git 管理起来很清爽。踩坑指南现象改了配置没反应还是老样子原因配置语法错误时WezTerm 会显示错误并回退到内置默认配置而不是报错退出。 解法看启动时的错误提示也可用wezterm --config font_size20这类命令行覆盖快速确认程序本身正常。现象Leader 键按了没反应或正常输入被吞原因Leader 是模态前缀timeout_milliseconds内没按第二个键会超时退出且只有声明为mods LEADER的键才走这套逻辑。 解法检查 key 表里是否漏写LEADER确认config.leader与快捷键在同一份配置里生效。现象Nerd Font 图标显示为空心方块原因主字体里没有该字形且没有声明回退。 解法用wezterm.font_with_fallback挂上SymbolsNerdFontMonoArch 用户记得装ttf-nerd-fonts-symbols-mono。现象Linux 上窗口无法拖动/透明不生效原因Wayland 下window_background_opacity依赖合成器支持部分合成器会忽略它。 解法先回 X11 验证效果再换支持背景效果的合成器KDE 有专门支持效果参考 docs/screenshots/wezterm-kde-background-blur.png。现象Flatpak 里wezterm cli连不上、查不到窗格目录原因沙箱隔离跨进程信息受限官方文档明确建议重度用户转原生包。 解法按 docs/install/linux.md 换 APT/Copr/AppImage 等原生安装方式。排障路径汇总速查与下一步关键配置速查字段名与源码定义一致见 config/src/config.rs配置项作用常见取值initial_cols/initial_rows新窗口初始尺寸120 / 28font_size/font字号 / 字体回退链13 /font_with_fallback({...})color_scheme内置配色Catppuccin Mocha 等leader前缀键{ keya, modsCTRL, timeout_milliseconds1000 }scrollback_lines回滚行数10000window_background_opacity窗口底色透明度0~11 为不透明enable_waylandWayland 支持truefront_end渲染引擎OpenGL / WebGpu / Softwaredefault_workspace默认工作区字符串名常用快捷键CTRLSHIFTR重载配置、CTRLSHIFTP命令面板、CTRLSHIFTA窗格选择器、Leader 后%/ _ / hjkl分屏与导航。下一步建议把本文的键位和配色片段合并进~/.wezterm.lua用wezterm cli list感受一下 mux 会话挑一个 docs/recipes/workspaces.md 里的多工作区例子复刻到本机配置进 git 仓库——它只是 Lua 文件天然适合版本管理。【免费下载链接】weztermA GPU-accelerated cross-platform terminal emulator and multiplexer written by wez and implemented in Rust项目地址: https://gitcode.com/GitHub_Trending/we/wezterm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
