企业官网建设流程全解析

WezTerm 的 default_domain 配置详解：从本地域切换到 WSL 域，控制终端启动时的默认复用域

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

default_domain是 WezTerm 在启动 GUI 时用于指定“默认多路复用域（multiplexing domain）”的配置项，它决定了终端窗口第一个标签页里的 shell 运行在哪里：是本机的 cmd/PowerShell，还是某个 WSL 发行版，甚至是远程的 SSH/TLS 域。本文以官方文档为主干，结合仓库源码讲解该配置的语义、WSL 场景下的典型用法、可配置的取值范围，以及它和default_mux_server_domain的区别，读完后你可以直接写出一份可用的.wezterm.lua配置。

什么是默认域，为什么需要它

WezTerm 的多路复用（multiplexing）能力建立在multiplexing domains这一概念之上：一个域（domain）就是一组窗口和标签页的集合。WezTerm 启动时会自动创建一个内置的local域来管理 UI 中的窗口与标签页，同时你也可以配置它去启动或连接额外的域（如 SSH、Unix socket、TLS、WSL 域）。更多背景参见 docs/multiplexing.md。

default_domain就是用来指定“GUI 启动时默认使用哪一个域”的配置项，其完整语义如下：

• 该选项只作用于 GUI。当启动 GUI（而不是使用serial或connect子命令）时，WezTerm 默认会把内置的"local"域设为默认多路复用域；
• "local"域代表直接在本机系统上启动的进程；
• 启动完成后，WezTerm 会在该域中打开第一个标签页（或工作区），因此修改默认域可以直接改变你打开终端时见到的是哪个 shell。

在源码层面，这一行为可以在 wezterm-gui/src/main.rs 中得到印证。构建初始 mux 时，默认域优先取命令行传入的名字，否则回落为config.default_domain，再回落为"local"：

// wezterm-gui/src/main.rs（setup_mux 内部） let default_name = default_domain_name.unwrap_or(config.default_domain.as_deref().unwrap_or("local")); let domain = mux.get_domain_by_name(default_name) .ok_or_else(|| anyhow::anyhow!( "desired default domain '{}' was not found in mux!?", default_name))?; mux.set_default_domain(&domain);

从这段代码可以看出两层含义：

1. default_domain的值必须对应 mux 中真实存在的域名，否则启动会直接报错（"desired default domain '...' was not found in mux!?"）；
2. 名字优先级是：wezterm start命令行参数 > 配置文件里的default_domain> 内置"local"。

配置项本身的定义位于 config/src/config.rs：

#[dynamic(default)] pub default_domain: Option<String>,

它是一个可选的字符串，未设置时即使用内置的local域。

最典型场景：Windows 用户一键进入 WSL

default_domain最常见的实战用途来自 Windows + WSL 用户。Windows 上默认的local域会启动cmd或powershell，如果希望打开 WezTerm 直接进入某个 Linux 发行版，不必手动敲wsl.exe，可以把默认域改为对应的 WSL 域。

WezTerm 会自动为本地已安装的 WSL 发行版生成名为WSL:<发行版名>的域。例如本机执行wsl -l -v得到：

; wsl -l -v NAME STATE VERSION * Ubuntu-18.04 Running 1

那么 WezTerm 默认就会创建一个名为WSL:Ubuntu-18.04的域。此时在.wezterm.lua中设置：

config.default_domain = 'WSL:Ubuntu-18.04'

启动 WezTerm 后，第一个标签页就会直接运行该 Ubuntu 发行版里的 shell，而不是cmd或powershell。

为什么 WSL 域优于直接调用 wsl.exe

文档特别强调，使用 WslDomain 而不是手动wsl.exe的优势在于：WezTerm 可以利用 shell integration 追踪 WSL 内部的当前工作目录，并在新开标签页或分割窗格时继承这个目录。如果只是手动执行wsl.exe，WezTerm 无法获知 WSL 里的 cwd，新开窗格只能回到默认目录，体验会差很多。

WslDomain 的字段与自动生成逻辑

WSL 域的结构（WslDomain）包含以下字段，均可在 config/src/wsl.rs 的 Rust 结构体定义中找到对应：

自动生成逻辑在 config/src/wsl.rs：Windows 下 WezTerm 调用wsl.exe -l -v解析输出，为每个发行版生成一个WslDomain。解析过程还带一个有趣的实现细节——由于wsl -l -v输出是 UTF-16 编码，源码专门实现了utf16_to_utf8转换（见 config/src/wsl.rs），并配套了针对输出文本的单元测试test_parse_wsl_distro_list（见 config/src/wsl.rs），测试数据里就包含了Arch、Ubuntu、docker-desktop等发行版。

wsl_domains配置项接受一个 WslDomain 列表，其默认值就是上面自动生成的这份列表，详见 docs/config/lua/config/wsl_domains.md。你也可以在 Lua 中调用wezterm.default_wsl_domains()拿到这份默认列表再按需修改，该函数在 config/src/lua.rs 中注册到 Lua 环境。

自定义 WslDomain 的完整示例

手动配置 WSL 域的写法如下（每个字段都有注释说明）：

config.wsl_domains = { { -- 该域的名字，在所有类型的域中必须唯一 name = 'WSL:Ubuntu-18.04', -- 发行版名称，必须与 `wsl -l -v` 输出中的名字一致才有效 distribution = 'Ubuntu-18.04', -- 在发行版内启动命令时使用的用户名； -- 省略时使用该发行版的默认用户 -- username = "hunter", -- 当 SpawnCommand 未指定目录时的默认工作目录 -- default_cwd = "/tmp", -- 默认要运行的命令，SpawnCommand 未覆盖时生效； -- 注意：也可以直接在 WSL 内部用 `chsh` 设置用户的默认 shell， -- 从而不必在这里指定 -- default_prog = {"fish"}, }, }

配置好之后，同样把config.default_domain指向该域的名字即可：

config.default_domain = 'WSL:Ubuntu-18.04'

其他可用的默认域类型

文档指出，虽然示例偏 WSL，但default_domain可以接受任意可用多路复用域的名字。除了内置的local域和 WSL 域，仓库支持的域还包括：

• SSH 域（SshDomain）：通过 SSH 通道连接到远程 WezTerm 多路复用器（远端必须安装兼容版本的 wezterm）。配置见 docs/config/lua/SshDomain.md。例如：

config.ssh_domains = { { name = 'my.server', remote_address = '192.168.1.1', username = 'wez', }, } config.default_domain = 'my.server'

• Unix 域（unix_domains）：通过 Unix socket 连接多路复用器，Linux、macOS 乃至 Windows（用于接入 WSL）都支持。最小配置是把 docs/config/lua/config/unix_domains.md（对应 docs/multiplexing.md）中的域名设进default_domain：

config.unix_domains = { { name = 'unix' }, } config.default_domain = 'unix'

若还想让 GUI 启动时自动连接该域，等价于wezterm connect unix的写法是设置config.default_gui_startup_args = { 'connect', 'unix' }。

• TLS 域（tls_servers / tls_clients）：通过 TLS 加密 TCP 连接远程多路复用器，配置详见 docs/config/lua/TlsDomainServer.md 与 docs/config/lua/TlsDomainClient.md。

把这些域配合default_domain使用，可以让 WezTerm 一启动就附着到指定的远程会话，而不是停留在本机 shell。需要注意：文档提醒default_domain只适用于 GUI；独立的 mux server 有另一个对应的选项default_mux_server_domain。

与 default_mux_server_domain 的区别

WezTerm 还有一个名字非常接近的配置项default_mux_server_domain（见 docs/config/lua/config/default_mux_server_domain.md），两者极易混淆，区别在于作用对象：

• default_domain：作用于GUI（启动 wezterm 图形界面时）；
• default_mux_server_domain：作用于独立的 mux server（wezterm-mux-server），且自 20230712 版本起可用。默认同样是"local"，可以改成如 ExecDomain 等其他域。

两者在配置结构体中相邻定义（config/src/config.rs），但语义上各管一端。

default_mux_server_domain还有一个值得注意的限制：不能把客户端类型的多路复用域（如 TLS、SSH、Unix 域）设为 mux server 的默认域，这是为了防止客户端连回服务器时产生递归。代码中同样有校验逻辑保证这一点。

相关源码与测试定位

如果你想深入验证本文所述行为，可以在仓库中按以下路径继续查阅：

• 配置结构体与默认值：config/src/config.rs（default_domain与default_mux_server_domain定义）
• GUI 启动时默认域解析：wezterm-gui/src/main.rs（setup_mux中的名字回退逻辑）以及 wezterm-gui/src/main.rs（当默认域不等于local时跳过自动附着已有 GUI 的逻辑）
• WSL 域自动生成与解析：config/src/wsl.rs 与 config/src/wsl.rs，配套单元测试 config/src/wsl.rs
• Lua 绑定：config/src/lua.rs（wezterm.default_wsl_domains()）
• 多路复用整体概念：docs/multiplexing.md

小结

一句话总结：default_domain决定了 WezTerm GUI 打开后第一个 shell 落在哪个域。对 Windows + WSL 用户而言，把它设为WSL:<发行版名>即可免去手动wsl.exe的步骤，并顺带获得基于 shell integration 的目录追踪能力；对需要远程工作的用户，则可以把它指向任意已配置的 SSH/Unix/TLS 域。配置时只需保证域名字与wsl -l -v输出或你的域配置保持一致，并注意它只作用于 GUI，与作用于 mux server 的default_mux_server_domain不要混淆。

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