WezTerm 使用

https://wezterm.org/

开发时常要一边运行服务，一边查看输出或执行测试。如果每次都打开新窗口，很容易分不清命令运行在哪里。这一节用 WezTerm 把 WSL 终端组织成标签页和分屏，并完成一次“运行服务、查看请求日志”的练习。

终端模拟器与 Shell

WezTerm 是一个跨平台终端模拟器，支持 GPU 渲染、标签页、分屏和 Lua 配置，也提供 SSH 与多路复用等扩展能力。本节先用到窗口、标签页、分屏和快捷键。

终端模拟器：WezTerm / Windows Terminal / Ubuntu Terminal
Shell：PowerShell / cmd / bash / zsh / fish
提示符：Starship
命令工具：git / python / node / docker
图标字体：Nerd Font

你可以把它理解为：用来打开命令行窗口的软件。

终端模拟器的核心作用是：

显示命令行界面
接收键盘输入
渲染文字、颜色、图标
管理标签页、分屏、快捷键
启动不同 Shell

上一节已经接触过 WSL。现在要分清终端窗口和窗口中运行的 Shell。

Shell 的职责

它们负责解释输入的命令。

例如输入：

bash

cd ~
ls
python3 --version

Shell 负责解析命令并启动相应程序；python main.py 中的 Python 程序由 Python 解释器运行。

终端窗口的职责

WezTerm 负责显示这个交互过程。

比如：

text

WezTerm
├── WSL Ubuntu
│   └── bash / zsh / fish
├── PowerShell
└── CMD

所以它们不是替代关系，而是组合关系。

现代终端工具链分层协同架构图

WezTerm 的使用场景

不同系统的终端软件有各自的界面和快捷键。WezTerm 可以让多个开发任务留在同一个窗口，并按需要配置统一的操作方式。它提供：

跨平台一致性好
配置能力更强
分屏、标签页体验好
快捷键可高度自定义
支持 Lua 配置
支持 SSH 域、WSL 域
字体、颜色、透明、背景控制更细

下面这些任务尤其适合用标签页和分屏组织：

多项目切换
一边跑服务，一边看日志
一边编辑文件，一边执行命令
经常连接远程服务器
想统一 Windows / Linux / macOS 终端体验

接下来先装好 Windows 版 WezTerm，再把默认终端设为上一节安装的 WSL Ubuntu。

安装 WezTerm

安装方式以 WezTerm 官方说明为准。本系列在 Windows 11 中安装 WezTerm，WSL Ubuntu 负责运行 Linux 命令；不要在 WSL 中执行下面的 Windows 安装命令。

Windows 安装

在 Windows PowerShell 中使用 winget：

powershell

winget install wez.wezterm

也可以从官方 Windows 安装页下载安装包。

安装后，从开始菜单打开 WezTerm。此时能看到命令行窗口即可，暂时不要求它自动进入 WSL。

Ubuntu 桌面安装

这条路线仅适用于 Ubuntu 桌面系统。如果按本系列使用 Windows＋WSL，继续配置 Windows 版 WezTerm 即可。Ubuntu 桌面使用 APT 安装前，先按照官方 Linux 安装说明配置仓库：

bash

curl -fsSL https://apt.fury.io/wez/gpg.key | sudo gpg --yes --dearmor -o /usr/share/keyrings/wezterm-fury.gpg
echo 'deb [signed-by=/usr/share/keyrings/wezterm-fury.gpg] https://apt.fury.io/wez/ * *' | sudo tee /etc/apt/sources.list.d/wezterm.list
sudo chmod 644 /usr/share/keyrings/wezterm-fury.gpg
sudo apt update
sudo apt install wezterm

配置文件与 WSL 发行版

Windows 上推荐把配置文件放在：

text

C:\Users\你的用户名\.wezterm.lua

也就是用户目录下面的：

text

.wezterm.lua

如果没有，就自己创建一个。

在 Windows PowerShell 中可以用记事本创建或打开：

powershell

notepad $HOME\.wezterm.lua

WezTerm 使用 Lua 作为配置语言。

先在 Windows PowerShell 中查看已安装的发行版：

powershell

wsl -l -v

上一节使用 wsl --install -d Ubuntu，所以下面的配置以 Ubuntu 为例。如果你的输出是 Ubuntu-22.04 等其他名称，须把后续代码中的 Ubuntu 全部替换为实际名称。

最小配置

先保存这个最小版本，确认 WezTerm 能进入 WSL。字体和主题稍后再加，便于定位配置问题：

lua

local wezterm = require("wezterm")
local config = wezterm.config_builder()

config.default_prog = { "wsl.exe", "-d", "Ubuntu" }

return config

config.default_prog 指定窗口默认启动的程序；这里调用 wsl.exe，并用 -d Ubuntu 指定发行版。保存文件后重新打开 WezTerm，应进入 Ubuntu Shell；输入 uname -s，看到 Linux 即可确认。WezTerm 通常会自动重新加载已保存的配置，也可以按 Ctrl + Shift + R 强制重新加载。

如果希望默认打开 Windows PowerShell，把上面那一行改为：

lua

config.default_prog = { "powershell.exe" }

WezTerm 宿主配置加载与 WSL 启动桥接链路图

快捷键与分屏

在最小配置的基础上加入按键。下面的完整代码可以直接替换 .wezterm.lua；其中 CurrentPaneDomain 表示在当前分屏所属环境中打开新标签页或新分屏。

lua

local wezterm = require("wezterm")
local act = wezterm.action
local config = wezterm.config_builder()

config.default_prog = { "wsl.exe", "-d", "Ubuntu" }

config.keys = {
  {
    key = "Enter",
    mods = "ALT",
    action = act.ToggleFullScreen,
  },
  {
    key = "t",
    mods = "CTRL|SHIFT",
    action = act.SpawnTab("CurrentPaneDomain"),
  },
  {
    key = "w",
    mods = "CTRL|SHIFT",
    action = act.CloseCurrentTab({ confirm = true }),
  },
  {
    key = "\\",
    mods = "CTRL|SHIFT",
    action = act.SplitHorizontal({ domain = "CurrentPaneDomain" }),
  },
  {
    key = "-",
    mods = "CTRL|SHIFT",
    action = act.SplitVertical({ domain = "CurrentPaneDomain" }),
  },
  {
    key = "h",
    mods = "ALT",
    action = act.ActivatePaneDirection("Left"),
  },
  {
    key = "l",
    mods = "ALT",
    action = act.ActivatePaneDirection("Right"),
  },
  {
    key = "k",
    mods = "ALT",
    action = act.ActivatePaneDirection("Up"),
  },
  {
    key = "j",
    mods = "ALT",
    action = act.ActivatePaneDirection("Down"),
  },
}

return config

保存后重新打开 WezTerm，按下面的组合键试一次：

Ctrl + Shift + t      新建标签页
Ctrl + Shift + w      关闭标签页
Ctrl + Shift + \      左右分屏
Ctrl + Shift + -      上下分屏
Alt + h/j/k/l         切换分屏
Alt + Enter           全屏
Ctrl + Shift + Alt + 方向键  调整分屏大小（WezTerm 默认快捷键）

SplitHorizontal 会创建左右两个分屏，SplitVertical 会创建上下两个分屏。调整大小沿用 WezTerm 的默认快捷键，无须重复配置。快捷键如与输入法或系统软件冲突，可在后面的常见问题中排查。

WezTerm 标签页、分屏与 Vim 导航操作全景图

完整配置

完成前面的练习后，可把字体、主题、窗口和启动菜单加入配置。先按附录在 Windows 安装 JetBrainsMono Nerd Font，然后把下面内容放到：

text

C:\Users\你的用户名\.wezterm.lua

这是一份完整文件，直接替换前面的最小配置；如果 wsl -l -v 显示的名称不是 Ubuntu，同时修改默认启动项和启动菜单中的发行版名称。

lua

local wezterm = require("wezterm")
local act = wezterm.action
local config = wezterm.config_builder()

-- 字体与显示
config.font = wezterm.font("JetBrainsMono Nerd Font")
config.font_size = 12.5
config.color_scheme = "Catppuccin Mocha"
config.window_background_opacity = 0.95

-- 默认启动 WSL
config.default_prog = { "wsl.exe", "-d", "Ubuntu" }

-- 窗口
config.initial_cols = 120
config.initial_rows = 32
config.window_decorations = "RESIZE"
config.enable_tab_bar = true
config.hide_tab_bar_if_only_one_tab = false

-- 启动菜单
config.launch_menu = {
  {
    label = "WSL Ubuntu",
    args = { "wsl.exe", "-d", "Ubuntu" },
  },
  {
    label = "PowerShell",
    args = { "powershell.exe" },
  },
  {
    label = "CMD",
    args = { "cmd.exe" },
  },
}

-- 快捷键
config.keys = {
  -- 打开启动菜单，选择 WSL / PowerShell / CMD
  {
    key = "o",
    mods = "CTRL|SHIFT",
    action = act.ShowLauncher,
  },

  -- 全屏
  {
    key = "Enter",
    mods = "ALT",
    action = act.ToggleFullScreen,
  },

  -- 新建/关闭标签页
  {
    key = "t",
    mods = "CTRL|SHIFT",
    action = act.SpawnTab("CurrentPaneDomain"),
  },
  {
    key = "w",
    mods = "CTRL|SHIFT",
    action = act.CloseCurrentTab({ confirm = true }),
  },

  -- 分屏
  {
    key = "\\",
    mods = "CTRL|SHIFT",
    action = act.SplitHorizontal({ domain = "CurrentPaneDomain" }),
  },
  {
    key = "-",
    mods = "CTRL|SHIFT",
    action = act.SplitVertical({ domain = "CurrentPaneDomain" }),
  },

  -- pane 切换：类似 vim
  {
    key = "h",
    mods = "ALT",
    action = act.ActivatePaneDirection("Left"),
  },
  {
    key = "l",
    mods = "ALT",
    action = act.ActivatePaneDirection("Right"),
  },
  {
    key = "k",
    mods = "ALT",
    action = act.ActivatePaneDirection("Up"),
  },
  {
    key = "j",
    mods = "ALT",
    action = act.ActivatePaneDirection("Down"),
  },

  -- 复制粘贴
  {
    key = "c",
    mods = "CTRL|SHIFT",
    action = act.CopyTo("Clipboard"),
  },
  {
    key = "v",
    mods = "CTRL|SHIFT",
    action = act.PasteFrom("Clipboard"),
  },
}

return config

保存后按 Ctrl + Shift + R 重新加载配置。按 Ctrl + Shift + o 打开启动菜单，分别能看到 WSL Ubuntu、PowerShell 和 CMD。这里使用 Windows 自带的 powershell.exe；只有另外安装了 PowerShell 7，才需要改用 pwsh.exe。

这几个选项控制最常见的显示和启动行为：

配置项	作用
`config.font`	设置字体
`config.font_size`	设置字号
`config.color_scheme`	设置配色主题
`config.window_background_opacity`	设置背景透明度
`config.default_prog`	设置默认启动程序

config.window_decorations = "RESIZE" 会隐藏系统标题栏并保留窗口边框；如果更习惯普通标题栏，删掉这一行即可。WezTerm 会自动加载 ~/.wezterm.lua 中的 Lua 配置；出现配置错误时先回退到前面的最小版本，再逐项恢复设置。

常见问题

1、字体未生效

如果配置了：

lua

config.font = wezterm.font("JetBrainsMono Nerd Font")

但 Windows 没有安装这个字体，显示效果可能和示例不同。WezTerm 内置 JetBrains Mono 和 Nerd Font Symbols，未配置专门的 Nerd Font 时也能先完成终端操作。

先按附录安装字体，再在 Windows PowerShell 中检查 WezTerm 实际使用的字体：

powershell

wezterm ls-fonts

若当前终端找不到 wezterm 命令，关闭并重新打开 Windows PowerShell，再执行一次。

2、分屏切换快捷键无响应

常见原因：

快捷键被系统或输入法占用
配置文件没保存
WezTerm 没重新加载配置
当前焦点不在 WezTerm

先确认配置文件已保存，按 Ctrl + Shift + R 重新加载。再在 Windows PowerShell 中检查实际生效的快捷键：

powershell

wezterm show-keys

如果按键被系统或输入法占用，可以把示例中的修饰键改成：

lua

mods = "CTRL|ALT"

修改后还要同步修改文中的按键记法，再尝试切换分屏。

3、未进入 WSL Ubuntu

先在 Windows PowerShell 运行 wsl -l -v，核对安装名称与 config.default_prog 中的名称是否完全一致。例如输出是 Ubuntu-22.04 时，应写 "Ubuntu-22.04"。如果 WezTerm 显示配置错误，先检查 .wezterm.lua 是否放在 Windows 用户目录、Lua 字符串的引号是否配对，再退回最小配置定位错误。

开发工作区示例

日常开发可以这样用：

Tab 1：项目后端
  左侧：编辑/执行命令
  右上：运行 FastAPI / Flask
  右下：查看日志 / 执行测试

Tab 2：项目前端
  左侧：pnpm dev
  右侧：git status / git commit

Tab 3：Docker
  docker compose up
  docker compose logs -f

Tab 4：服务器
  ssh root@server

这些是同一套标签页和分屏操作在真实项目里的延伸。SSH、Docker 和前后端命令仍由对应的 Shell 或程序执行，WezTerm 负责组织窗口。

现代化全栈开发：WezTerm 多标签与多分屏实战工作区全景图

本章先掌握标签页、分屏和常见配置。状态栏、主题自动切换、按项目启动工作区、多路复用、SSH 域、鼠标行为和按键表可在需要时继续查阅；后续章节会介绍 fish 与 Starship。

附录：字体安装

Windows 字体安装

从 Nerd Fonts 的 JetBrainsMono 发布包下载字体并解压。

打开解压目录，选中 .ttf 字体文件，右键选择“安装”。发布包的内部目录可能随版本变化，以实际解压结果为准。安装完成后重新打开 WezTerm。

本系列的 WezTerm 运行在 Windows，因此优先安装到 Windows；只在 Ubuntu 桌面运行 WezTerm 时才需要执行下面的 Linux 步骤。

Ubuntu 桌面字体安装

bash

mkdir -p ~/.local/share/fonts
cd /tmp

wget https://github.com/ryanoasis/nerd-fonts/releases/latest/download/JetBrainsMono.zip

unzip JetBrainsMono.zip -d JetBrainsMono
find JetBrainsMono -type f -name '*.ttf' -exec cp {} ~/.local/share/fonts/ \;

fc-cache -fv

如果缺少 wget、unzip、fc-cache，先在 Ubuntu 桌面安装对应软件包：sudo apt install wget unzip fontconfig。

如果下载速度过慢，可以使用下面分享的文件；下载后同样确认其中是 Nerd Font 字体文件，再按对应系统安装。

通过网盘分享的文件：JetBrainsMono-2.304.zip 链接：https://pan.baidu.com/s/11cvfleCgroPPUMNZHjsKtg?pwd=6447 提取码：6447

WezTerm 使用 ​

终端模拟器与 Shell ​

Shell 的职责 ​

终端窗口的职责 ​

WezTerm 的使用场景 ​

安装 WezTerm ​

Windows 安装 ​

Ubuntu 桌面安装 ​

配置文件与 WSL 发行版 ​

最小配置 ​

快捷键与分屏 ​

完整配置 ​

常见问题 ​

开发工作区示例 ​

附录：字体安装 ​

WezTerm 使用

终端模拟器与 Shell

Shell 的职责

终端窗口的职责

WezTerm 的使用场景

安装 WezTerm

Windows 安装

Ubuntu 桌面安装

配置文件与 WSL 发行版

最小配置

快捷键与分屏

完整配置

常见问题

开发工作区示例

附录：字体安装