Net::SSH 是 Ruby 生态中最常用的 SSH 客户端库，而 Net::SSH::Config 作为它的配置解析模块，负责读取 ~/.ssh/config 这样的 SSH 客户端配置文件。很多开发者以为只要在 ~/.ssh/config 中写好了 Host 别名，Net::SSH 就会自动读取并使用这些配置，但实际运行起来却发现连接请求并没有按照预期走。问题往往出在对这个模块的工作原理不够了解。
认识 Net::SSH::Config 模块
Net::SSH::Config 是 Net::SSH 内部用来加载 SSH 配置文件的工具模块，它不需要额外安装，随 net-ssh gem 一起分发。该模块的核心职责是从指定的路径读取 SSH 客户端配置文件，将文本内容转换成一个 Ruby hash，然后根据传入的主机名去匹配对应的配置条目并返回合并后的配置。
模块中最常用的两个方法是 Net::SSH::Config.load 和 Net::SSH::Config.for。load 方法接受一个文件路径，返回整个配置文件解析后的 hash 结构；for 方法则接受一个主机名（可以是别名）和一个可选的配置 hash，它从默认位置加载文件，找到匹配的 Host 条目，并将相关参数合并后返回。具体使用方式看下面的示例：
require 'net/ssh'
# 直接加载指定配置文件
config = Net::SSH::Config.load('/home/user/.ssh/config')
puts config.inspect
# 根据别名获取最终配置
opts = Net::SSH::Config.for('my-server')
puts opts.inspect
上面的代码运行后，for 方法返回的 hash 中包含了匹配到的 HostName、User、Port 等参数。注意，for 方法默认会读取 ~/.ssh/config 和 ~/.ssh/config.d 目录下（如果存在的话）的配置文件，但这一行为在某些旧版本中并不完全一致，所以显式指定路径会更稳妥。若想完全控制加载源头，可以传入 file 参数：
opts = Net::SSH::Config.for('my-server', file: '/path/to/config')
~/.ssh/config 文件的解析细节
SSH 配置文件的语法非常简洁，每一行要么是注释、空行，要么是“参数名 参数值”的键值对。参数名不区分大小写，参数值可以带有双引号或单引号。Net::SSH::Config 在解析时会逐行剥离开头的空白字符，跳过 # 开头的注释行，并将每个参数的键名转换成小写符号形式。
举个例子，一个典型的配置片段如下：
# 本机测试环境
Host dev
HostName 192.168.1.10
User root
Port 2222
IdentityFile ~/.ssh/id_rsa_dev
Host production
HostName prod.ippipp.com
User deploy
ServerAliveInterval 60
上述配置经 Net::SSH::Config.load 解析后，会得到一个以 Host 条目为键的 hash。for 方法在匹配时，会遍历这些条目，检查传入的主机名是否与某个 Host 值相符。如果相符，就把该条目下的参数取出来，同时还会将全局配置（没有 Host 前缀的配置，或 Host * 条目）作为基础配置合并进去。
这里有一个容易忽略的细节：配置文件中的参数名如果带连字符，比如 ServerAliveInterval，Net::SSH::Config 会将其转换成 :server_alive_interval 这样的下划线符号形式。这样做是为了与 Net::SSH 连接时的选项键名保持一致。因此，在代码中合并配置时，你可以直接通过 opts[:server_alive_interval] 来访问这个值。
别名匹配规则与通配符处理
别名匹配是很多人踩坑的地方。OpenSSH 在查阅配置时，是按照文件顺序从上往下查找，找到第一个匹配的 Host 条目后就停下来，后面的同类参数不会覆盖前面的。Net::SSH::Config 也遵循这一原则，因此你写在后面的 Host 别名如果与前一个通配符匹配重复，前面的配置会优先生效。
通配符的支持方面，Host 值中可以使用 * 和 ?。* 匹配任意长度的任意字符，? 匹配单个字符。例如 Host *.ippipp.com 可以匹配 api.ippipp.com，也能匹配 prod.api.ippipp.com，但不会匹配 ippipp.com。若要匹配没有子域的情况，可以同时写两行。此外，以叹号 ! 开头的模式表示排除匹配，比如 Host !*.ippipp.com 表示除了 ippipp.com 域之外的主机。Net::SSH::Config 内部实现了类似的匹配逻辑，但不同版本之间的支持程度略有差异，使用前最好先验证一下当前 gem 版本的源码。
看下面的例子，配置中有两个 Host 条目，一个精确匹配，一个通配符匹配：
Host web-*
User webadmin
Host web-01
User deploy
Port 2222
这里如果用 Net::SSH::Config.for('web-01')，匹配流程会先看到 web-*，它匹配成功，于是 User 被设置为 webadmin。接着继续向下，又遇到 web-01，也匹配成功，User 被覆盖为 deploy，Port 被设置为 2222。最终得到的配置里，User 是 deploy，Port 是 2222。如果调换两个条目的顺序，那么 web-* 会先匹配并设置 User 为 webadmin，而后续没有其他匹配，最终 User 就是 webadmin，Port 未定义。在实际项目中，最好将精确配置放在通配符配置之前，避免出现不可预期的覆盖。
另一个常见误区是：调用 Net::SSH.start('web-01') 时，Net::SSH 不会自动去解析 ~/.ssh/config。即使你配置了别名，Net::SSH 默认也只会把它当作真实的主机名去连接。只有显式传入 config: true，才会触发 Net::SSH 去查找配置文件。Net::SSH::Config.for 方法是手动获取配置的手段，而 Net::SSH.start 的 config 参数会自动调用 for 进行合并。因此，正确写法是：
Net::SSH.start('web-01', nil, config: true, password: 'xxx') do |ssh|
# 这里连接的主机来自配置文件的 HostName
end
当 config: true 时，Net::SSH 会读取用户的 ~/.ssh/config，并用别名 web-01 去匹配。如果匹配到条目中包含 HostName，实际连接的就是 HostName 指定的地址；如果只有 HostName 而没有 User，那么 User 还得通过其他方式指定。注意，如果同时通过参数显式传入了 user 和配置文件中匹配到的 User，显式参数的优先级更高。这一点与 OpenSSH 的行为也是一致的。
参数继承与优先级
SSH 配置支持全局参数，也就是写在所有 Host 条目之前、不带 Host 前缀的参数。这些参数作为默认值会被所有匹配的 Host 条目继承。Net::SSH::Config 在解析时，会将全局参数作为一个基础 hash，之后每匹配一个 Host 条目，就把该条目的参数覆盖到基础 hash 中。这样做既能减少重复配置，也符合 OpenSSH 的设计意图。
值得注意的是，Net::SSH::Config 并不会处理 Host 条目内部的嵌套继承。比如一个 Host 条目中的配置无法引用另一个 Host 条目的配置值，也不会像编程语言那样支持变量替换。IdentityFile 里的 ~ 会被展开为当前用户的主目录，但其他像 %d、%h 之类的令牌占位符，模块内部只做了部分处理。如果你在配置中用到了 %h（代表目标主机名），在没有匹配到 HostName 参数时，%h 会被替换为原始别名；而一旦配置了 HostName，%h 就会被替换成 HostName 的值。这种细节在调试时很容易让人迷惑。
为了避免依赖这些隐晦行为，建议在 Ruby 代码中直接维护一份配置 hash，或者完全依赖 Net::SSH::Config.for 的返回值，再做一层显式的参数合并。下面给出一个完整的示例，演示如何手动加载配置并连接：
require 'net/ssh'
host = 'mydev'
opts = Net::SSH::Config.for(host)
# 如果配置文件没有提供 User，则使用默认值
opts[:user] ||= ENV['USER']
Net::SSH.start(host, nil, opts) do |ssh|
puts ssh.exec!('hostname')
end
这个例子中，Net::SSH.start 的第二个参数传 nil，用户名完全由 opts 决定。如果配置文件里没有对应条目，for 方法会返回空 hash，连接可能失败。此时可以打印 opts 看看实际解析出了什么。
常见坑点与最佳实践
第一个坑是配置文件权限问题。SSH 客户端对 ~/.ssh/config 的权限非常敏感，如果文件权限过于开放，OpenSSH 会直接忽略它。Net::SSH::Config 并不会检查权限，但如果你发现 OpenSSH 能识别而在 Net::SSH 中不生效，可以先用 Net::SSH::Config.load 手动加载一遍，确认内容是否被正确解析。另一个坑是配置文件行尾的 Windows 换行符 \r\n，Net::SSH::Config 在读取时虽然会去首尾空白，但有时候参数值中仍然会残留 \r，导致匹配失败。解决办法是确保配置文件是 Unix 换行符。
第二个坑是 Host 匹配时的大小写问题。OpenSSH 的 Host 匹配是区分大小写的，Net::SSH::Config 同样如此。所以别名的拼写必须与命令行使用的完全一致。如果你的别名包含大写字母，在 Net::SSH.start 中也要同样使用大写。另外，配置文件中参数名虽然不区分大小写，但 Host 的值区分，这一点必须牢记。
第三个坑是多个配置文件路径。Net::SSH 通常只读取 ~/.ssh/config，或者系统级的 /etc/ssh/ssh_config。如果你需要读取其他位置的配置，for 方法提供了 file 参数。但注意，Net::SSH.start 的 config 选项只接受布尔值或字符串。如果是字符串，它会被当作配置文件路径传给 for。所以你可以这样写：
Net::SSH.start('web-01', nil, config: '/tmp/my_config')
这种做法在测试环境、CI 环境中非常有用。最后，建议在关键业务代码中显式传递 config: true，并且在启动时打印或缓存解析后的配置，这样一旦连接异常，可以迅速定位是配置文件写错了，还是匹配逻辑出现了偏差。通过合理利用 Net::SSH::Config 的解析能力，完全可以让 Net::SSH 项目享受到 OpenSSH 风格的配置管理便利。
RubyNet::SSH::ConfigSSH别名匹配修改时间：2026-08-22 12:50:16