wezterm.default_ssh_domains()：从 ~/.ssh/config 自动生成 SSH 域并定制多路复用会话

wezterm.default_ssh_domains()：从 ~/.ssh/config 自动生成 SSH 域并定制多路复用会话

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

wezterm.default_ssh_domains()是 WezTerm 提供的一个 Lua 配置函数，它读取你本机~/.ssh/config中定义的主机，自动生成一组可直接使用的 SSH 域（domain）对象。阅读本文后，你将掌握该函数的返回值结构与默认行为、它如何同时生成普通 SSH 域与多路复用域，以及如何在赋值给config.ssh_domains之前批量改写这些域，从而定制远程会话体验。

函数概览与适用版本

wezterm.default_ssh_domains()

该函数自版本20230408-112425-69ae8472起可用（对应 changelog 中的相关条目）。它的作用非常简单直接：基于你在~/.ssh/config中发现的全部主机，计算出一组 SshDomain 对象列表，便于你直接（或在修改后）赋给配置项config.ssh_domains。

从源码角度看，这个 Lua 函数在 lua-api-crates/ssh-funcs/src/lib.rs 中注册：

wezterm_mod.set( "default_ssh_domains", lua.create_function(|_, ()| Ok(config::SshDomain::default_domains()))?, )?;

也就是说，它本质上是 Rust 侧SshDomain::default_domains()的薄封装，真正的生成逻辑位于 config/src/ssh.rs。

返回值：每个主机对应两个域

对于~/.ssh/config中的每一个主机，该函数都会生成两个域并返回在列表中：

前者不要求远端安装 WezTerm，代价是失去多路复用能力；后者要求远端安装 WezTerm，但可以获得完整的 tab/pane 多路复用与断线重连体验。所有返回的域都继承了~/.ssh/config中的连接参数（用户名、端口、身份文件等），并在默认情况下读取local_echo_threshold_ms的默认阈值。

这段逻辑在 config/src/ssh.rs 中有完整实现：遍历wezterm_ssh::Config::enumerate_hosts()的结果，为每个主机分别构造一个SSH:前缀的普通域和一个SSHMUX:前缀的多路复用域，最终合并为一个列表返回。

哪些主机会被枚举？

主机枚举发生在 wezterm-ssh/src/config.rs 的enumerate_hosts()中。需要注意以下几点：

• 只有Host（以及Match）配置块中字面量、非通配符的主机名才会被收集；
• 被!前缀否定的模式会被跳过；
• 通过Host *之类的通配符匹配不会生成具体域名。

因此，如果你在~/.ssh/config里习惯用Host *.example.com之类的通配块，那么default_ssh_domains()并不会为每一个实际主机生成域——只有显式写出的主机名才会被枚举。

配置文件从哪里读取？

default_ssh_domains()内部通过wezterm_ssh::Config::add_default_config_files()加载默认 SSH 配置文件（见 wezterm-ssh/src/config.rs）：

• ~/.ssh/config（Unix / macOS / Windows 下均优先读取用户主目录）；
• /etc/ssh/ssh_config（系统级配置）；
• Windows 上还会读取%SystemDrive%/ProgramData/ssh/ssh_config。

这意味着函数产出的域会尊重你在这些文件中配置的全局/主机级选项。

设计目的：赋值前提供改写机会

函数文档明确说明，其预期用途是给你一个机会，在把结果赋给config.ssh_domains之前，对返回的信息进行编辑/调整。

例如，如果你的~/.ssh/config中所有主机都是 Unix 机器，你可能希望告知 WezTerm 这一点，这样即使在普通的 SSH 会话中，诸如“在新标签页中继承当前目录打开”这类依赖 Shell 集成的功能也能正常工作：

config.ssh_domains = wezterm.default_ssh_domains() for _, dom in ipairs(config.ssh_domains) do dom.assume_shell = 'Posix' end

这个例子中，assume_shell会被统一设置为'Posix'，告诉 WezTerm 远端运行的是 POSIX/Bourne Shell 兼容环境，从而允许在multiplexing = "None"的普通 SSH 域中，通过env -C DIR $SHELL之类的语法在新开 tab/pane 时继承远端当前目录（详情见 Shell Integration）。

为什么需要手动改写？

一个关键事实是：默认情况下 SSH 域并不为普通 SSH 会话启用 Shell 集成感知。SshDomain的assume_shell字段默认值是"Unknown"（见 config/src/ssh.rs 中Shell枚举的默认实现），此时 WezTerm 无法对远端 Shell 做任何假设。而default_ssh_domains()生成的两个域中，普通 SSH 域（SSH:前缀）的multiplexing为None，这正是需要assume_shell配合的场景。

更多可改写的字段

返回的每个域都是完整的 SshDomain 对象，你可以批量或按名称筛选后修改其任意字段，包括但不限于：

• username：覆盖 SSH 认证用户名；
• no_agent_auth：设为true可禁用 agent 认证；
• connect_automatically：设为true可在启动时自动连接该域；
• timeout：指定读超时时间；
• remote_wezterm_path：指定远端 wezterm 二进制路径（当它不在 SSH 配置的$PATH中时尤其有用）；
• multiplexing："WezTerm"（默认，需要远端安装 wezterm）或"None"（不使用多路复用，等价于wezterm ssh，断连会丢失 panes/tabs）；
• ssh_option：以键值表形式覆盖 SSH 配置选项，例如identityfile；
• local_echo_threshold_ms：设置预测性本地回显的往返延迟阈值（仅对multiplexing = "WezTerm"生效）。

与 config.ssh_domains 的默认关系

如果你没有在配置中显式设置ssh_domains，WezTerm 会默认表现得如同你写了下面这行（见 ssh_domains 配置文档）：

config.ssh_domains = wezterm.default_ssh_domains()

对应实现位于 config/src/config.rs：

pub fn ssh_domains(&self) -> Vec<SshDomain> { if let Some(domains) = &self.ssh_domains { domains.clone() } else { SshDomain::default_domains() } }

也就是说，默认行为与你主动调用该函数并赋值完全等价。如果你希望拥有比默认更精细的控制（例如统一设置assume_shell、为某些主机指定default_prog、或删除你不想要的主机域），就需要显式调用该函数后再赋值。

完整实战示例

下面是一个更完整的配置片段，展示了如何基于自动生成的域做细粒度定制：

local wezterm = require 'wezterm' local config = {} -- 基于 ~/.ssh/config 自动生成 SSH 域 config.ssh_domains = wezterm.default_ssh_domains() -- 统一告知 WezTerm：这些主机都是 POSIX 环境 -- （使普通 SSH 会话也能继承远端当前目录） for _, dom in ipairs(config.ssh_domains) do dom.assume_shell = 'Posix' end -- 针对特定主机做额外定制：为多路复用域指定远端 wezterm 路径 for _, dom in ipairs(config.ssh_domains) do if dom.name == 'SSHMUX:my-server' then dom.remote_wezterm_path = '/home/me/bin/wezterm' dom.local_echo_threshold_ms = 20 -- 高延迟网络下开启预测性回显 end end -- 如果你想在启动时自动进入某个域，可以配合 default_domain： -- config.default_domain = 'SSH:my-server' return config

关于default_domain与 SSH 域的配合（例如将multiplexing = "None"的 SSH 域设为默认域，以便自动接入本地 WSL 实例），可进一步参考 default_domain 配置文档 与 多路复用（Multiplexing）。

小结

wezterm.default_ssh_domains()将你熟悉的~/.ssh/config资产无缝转化为 WezTerm 的 SSH 域：

• 它为每个字面量主机生成普通 SSH（SSH:）与多路复用（SSHMUX:）两个域；
• 它只在未设置config.ssh_domains时作为默认值自动生效；
• 它返回完整的 SshDomain 对象，赋予你在赋值前批量改写的能力——这正是它的设计初衷。

借助它，你既可以用最少的配置获得与~/.ssh/config同步的远程会话入口，又可以通过一次循环遍历，为全部或部分主机注入assume_shell、local_echo_threshold_ms、remote_wezterm_path等高级设置，让普通 SSH 会话也拥有流畅的目录继承体验。

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