WezTerm 多路复用入门指南：把终端会话留在后台，一次配置长期有效-平芜编程栈

WezTerm 多路复用入门指南：把终端会话留在后台，一次配置长期有效

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

WezTerm 是一款用 Rust 编写、GPU 加速的终端模拟器。它的多路复用（mux）功能可以在关闭所有窗口后保留正在运行的会话，重新连接时原样恢复，避免你因关错窗口或断网而重跑任务。

先搞懂"域"：30秒版本

WezTerm 多路复用的核心单位叫域（Domain），一个域就是一组窗口、标签页和窗格的集合。可以把它想象成餐厅：

前台窗口：你眼前看到的 WezTerm 界面，只是"店面"；
域：一个独立的经营部门，可以有自己的菜单（标签页布局）；
后台 mux 服务：wezterm-mux-server进程，相当于后厨主管，负责真正维护会话状态。

关闭窗口只是撤掉了"店面"，后厨还在运转，会话就还在。域分三种：本机默认创建的Local 域、走 Unix 套接字的Unix 域、走 SSH 通道的SSH 域。

场景一：本机标签页不掉线（Unix 域）

WezTerm mux 最小配置

在.wezterm.lua中加入以下两行配置即可：

config.unix_domains = { { name = 'unix' }, } config.default_gui_startup_args = { 'connect', 'unix' }

name = 'unix'是给域起的名字，在全部域中必须唯一；第二行让 WezTerm 启动时自动接入这个域，等价于每次手动执行wezterm connect unix。如果不想自动连接，删掉第二行即可。

验证 mux 服务在跑

# 手动连接该域 wezterm connect unix # 列出当前域内的窗口、标签和窗格 wezterm cli list

wezterm cli list输出的是标签页树结构，能看到内容就说明客户端与后台服务已正常通信。

可选参数

常用字段一览，均未设置时 WezTerm 会取合理默认值：

字段	作用
`socket_path`	指定套接字文件位置，默认在运行时目录下的`sock`
`local_echo_threshold_ms`	往返延迟超过阈值（毫秒）时，客户端本地预测回显按键，掩盖卡顿
`skip_permissions_check`	跳过对套接字属主的权限校验，多用户机器上不要开
`no_serve_automatically`	为 true 时连接失败也不尝试拉起服务器

本机场景一般只需前两行配置；延迟敏感的操作（如大量输入）再考虑local_echo_threshold_ms。

场景二：远程服务器长期会话（SSH 域）

SSH 域的前提：远端主机上必须安装兼容版本的 WezTerm。连接建立后，WezTerm 会在远端启动wezterm-mux-server，本地窗口挂到远端的会话上——这就是终端会话保持的典型用法。

显式声明一个 SSH 域

config.ssh_domains = { { name = 'prod-server', remote_address = '192.168.1.100', username = 'devops', }, }

连接与验证：

wezterm connect prod-server # 在现有 WezTerm 实例中开新标签页接入同一域 wezterm cli spawn --domain-name prod-server

remote_address同时用于匹配你~/.ssh/config里对应主机的设置，建议配合 SSH 密钥认证。

复用已有 SSH 配置

WezTerm 会自动读取~/.ssh/config，为每个主机生成两类域：普通 SSH 连接带SSH:前缀，多路复用连接带SSHMUX:前缀。这样无需任何 WezTerm 配置：

wezterm connect SSHMUX:staging

两台路径按需选择：主机少且参数固定时用显式声明；主机多、已有成熟 SSH 配置时用SSHMUX:自动域。

场景三：Windows 下接 WSL

这条链路依赖 Unix 域的 AF_UNIX 互操作，目前仅支持 WSL 1。两端各改一段配置。

WSL 侧（Linux 里的 .wezterm.lua）

config.unix_domains = { { name = 'wsl', -- 套接字放到 NTFS 挂载路径，让 Windows 侧能访问 socket_path = '/mnt/c/Users/USERNAME/.local/share/wezterm/sock', -- NTFS 上权限概念失真，需跳过检查 skip_permissions_check = true, }, }

Windows 侧

config.unix_domains = { { name = 'wsl', serve_command = { 'wsl', 'wezterm-mux-server', '--daemonize' } }, } config.default_gui_startup_args = { 'connect', 'wsl' }

配置完成后从 Windows 启动 WezTerm，默认就会进入 WSL 会话，之后新建的标签页也落在 WSL 一侧。serve_command的作用就是让 Windows 侧通过wsl命令把 mux 服务拉进容器里。

连不上？按顺序排查

核对两端版本。SSH 域要求远端安装兼容版本的 WezTerm，先分别在两端执行wezterm --version比对。
确认套接字路径与权限。找到实际使用的socket_path（默认在运行时目录下），执行ls -la检查文件存在、属主正确；skip_permissions_check只在 WSL 这类特殊场景下使用。
开调试日志定位原因。