Lima 实例 SSH 连接完全指南：ssh.config、~/.ssh/config 集成与无配置文件直连

2026-09-12 17:58:16作者：裘旻烁

Lima 在创建并启动 Linux 虚拟机实例后，除了官方推荐的 limactl shell 之外，还为每台实例生成标准的 OpenSSH 配置文件 ssh.config，让用户可以用原生 ssh 客户端直接连接，从而与 VS Code Remote Development、rsync、scp、Ansible 等一切依赖 SSH 生态的工具无缝互通。本文以 Lima 官方使用文档为主线，结合仓库内 ssh.config 的生成与消费源码，系统讲解三种连接方式、底层实现原理以及安全相关配置细节，读完即可在实际项目中直接套用。

为什么 Lima 会为每个实例生成 ssh.config

Lima 的核心交互方式是 limactl shell <INSTANCE>（default 实例可简写为 lima），但它本质上仍然依赖宿主机上的 OpenSSH 客户端去连接虚拟机内部。为了让"任何期望 SSH 连接性的软件"都能直接与 Lima 虚拟机通信，Lima 会在每个实例的目录下生成一份标准格式的 SSH 配置文件。

从仓库源码可以看出文件命名与位置的约定：

实例目录下该文件名为 ssh.config，定义于 pkg/limatype/filenames/filenames.go（常量 SSHConfig = "ssh.config"）；
实例目录本身位于 ~/.lima/<INSTANCE>/，因此 default 实例的配置文件路径为 ~/.lima/default/ssh.config；
在 pkg/store/instance.go 中，每次列出/检查实例时，SSHLocalPort（SSH 本地转发端口）与 SSHConfigFile 都会被填充到实例数据中，SSHConfigFile 正是 filepath.Join(instDir, filenames.SSHConfig)。

这份 ssh.config 的内容由 pkg/sshutil/format.go 中的 Format 函数以 config 格式生成，采用标准的 ~/.ssh/config 语法，例如：

Host lima-default
  IdentityFile "/Users/example/.lima/_config/user"
  User example
  Hostname 127.0.0.1
  Port 60022

其中：

Host lima-default：主机别名，由实例名派生（lima-<INSTANCE>），定义于 pkg/instance/hostname/hostname.go；
IdentityFile：指向 Lima 为每个用户生成的专用私钥 ~/.lima/_config/user（生成逻辑见下文）；
Hostname 127.0.0.1：SSH 通过宿主机上的本地端口转发进入虚拟机；
Port：该实例的 SSH 本地转发端口（可通过 limactl list 查询）。

方式一：通过 -F 指定配置文件直连

官方文档给出的最直接用法是先用 limactl ls 查出配置文件的绝对路径，再用 ssh -F 指定该配置并连接：

$ limactl ls --format='{{.SSHConfigFile}}' default
/Users/example/.lima/default/ssh.config

$ ssh -F /Users/example/.lima/default/ssh.config lima-default

两条命令的关键点：

limactl ls --format='{{.SSHConfigFile}}' 是 Go template 形式的格式化输出，limactl ls 是 limactl list 的别名（见 cmd/limactl/list.go），.SSHConfigFile 对应 pkg/limatype/lima_instance.go 中的 SSHConfigFile 字段；
-F 是 OpenSSH 的"使用指定配置文件"选项，lima-default 是配置文件中的 Host 别名；
这一用法对任何期望 SSH 连接性的软件（rsync、scp、Ansible 等）都适用，因为它们都可以用 -F 指定配置文件。

需要说明的是，仓库中旧的 limactl show-ssh 命令已被标记为 DEPRECATED，其帮助信息（见 cmd/limactl/show-ssh.go）明确建议改用 ssh -F <dir>/default/ssh.config lima-default。该命令目前仍保留 cmd、args、options、config 四种输出格式（见 pkg/sshutil/format.go），但不建议在新代码中依赖它。

方式二：通过 Include 集成到 ~/.ssh/config，实现免 -F 直连

如果你希望无需每次指定 -F，只需在 ~/.ssh/config 中加入一行：

Include ~/.lima/*/ssh.config

之后即可直接连接：

ssh lima-default

原理说明：OpenSSH 从 7.3p1 起支持 Include 指令，它会把匹配的通配符路径（这里匹配 ~/.lima/ 下所有实例的 ssh.config）当作配置片段加载进全局配置。这样每个 Lima 实例的 Host 别名（lima-<INSTANCE>）都会自动可用，新建实例也无需修改 ~/.ssh/config。

这一配置的典型价值正是官方文档点名的场景：Visual Studio Code 的 Remote Development（远程开发）模式，详见仓库文档 website/content/en/docs/examples/vscode.md。VS Code Remote-SSH 插件天然读取 ~/.ssh/config，加入 Include 一行后，VS Code 就能直接列出 lima-default 作为远程主机目标，无需额外配置。

方式三：无配置文件直连（适用于不支持配置文件的 SSH 客户端）

如果你的 SSH 客户端不支持配置文件（例如某些嵌入式环境、自定义脚本或精简客户端），可以完全放弃 ssh.config，用等价的命令行参数直连：

ssh -p <PORT> -i ~/.lima/_config/user -o NoHostAuthenticationForLocalhost=yes 127.0.0.1

其中端口号用下面的命令查询：

limactl list --format '{{ .SSHLocalPort }}' default

对照分析这条命令的每个部分：

-p <PORT>：SSH 端口，即实例的 SSHLocalPort 字段（见 pkg/limatype/lima_instance.go）；该端口是 Lima 在实例启动时分配给本地端口转发的动态端口，因此必须实时查询而不能写死；
-i ~/.lima/_config/user：使用 Lima 生成的专用私钥（私钥路径常量 UserPrivateKey = "user" 定义于 pkg/limatype/filenames/filenames.go）；
-o NoHostAuthenticationForLocalhost=yes：跳过对 localhost 的主机密钥确认，避免首次连接出现交互式指纹确认导致脚本卡死；
127.0.0.1：SSH 隧道建立在宿主机回环地址上。

此外官方文档提示可参考 ~/.lima/default/ssh.config——即方式一生成的配置文件内容，它本身就是上述等价参数的结构化表达，遇到无法使用配置文件的环境时，可以照抄其中的 Hostname、Port、IdentityFile 字段。

底层支撑：Lima 的 SSH 密钥与连接参数从何而来

理解三种连接方式后，有必要知道它们背后共用的两套机制：密钥体系与连接参数生成。

专用密钥对：~/.lima/_config/user

Lima 在首次使用时会在配置目录（默认为 ~/.lima/_config）生成无口令的 ed25519 密钥对 user / user.pub，生成逻辑位于 pkg/sshutil/sshutil.go 的 DefaultPubKeys 函数：调用 ssh-keygen -t ed25519 -q -N "" -C "lima"（-N "" 表示无口令，-C "lima" 表示注释为 lima），并在目录加锁（lockutil.WithDirLock）防止并发重复生成。同时，如果配置了 loadDotSSH（对应 YAML 中 ssh.loadDotSSHPubKeys），还会把 ~/.ssh/*.pub 一并注入虚拟机，让已有公钥也能直接登录。

连接参数：CommonOpts 与 SSHOpts

ssh.config 中的各项参数并非手写，而是由 pkg/sshutil/sshutil.go 的两个函数程序化生成：

CommonOpts（pkg/sshutil/sshutil.go）：总是包含 IdentityFile 选项，并追加 StrictHostKeyChecking=no、UserKnownHostsFile=/dev/null、NoHostAuthenticationForLocalhost=yes、PreferredAuthentications=publickey、Compression=no、BatchMode=yes、IdentitiesOnly=yes 等安全与自动化友好选项；OpenSSH ≥ 8.1 时还会根据 CPU 是否支持 AES 加速，动态选择优先 aes128-gcm@openssh.com / aes256-gcm@openssh.com 还是 chacha20-poly1305@openssh.com 作为首选密码套件；
SSHOpts（pkg/sshutil/sshutil.go）：在 CommonOpts 之上追加 User=<用户名>、ControlMaster=auto、ControlPath=<实例目录>/ssh.sock、ControlPersist=yes，并视 ssh.forwardAgent、ssh.forwardX11、ssh.forwardX11Trusted 配置追加 ForwardAgent=yes、ForwardX11=yes、ForwardX11Trusted=yes。

正因如此，手工直连命令（方式三）与配置文件（方式一、方式二）在参数语义上完全一致，区别仅在于表达载体不同。若需查看某一实例当前生成的完整 SSH 选项，可运行（该命令虽已废弃，但 config 格式输出仍与 ssh.config 内容对应）：

limactl show-ssh --format=config default

三种方式对比与选型建议

场景	推荐方式	命令/配置要点
单次、临时连接，或脚本中动态连接	方式一：`ssh -F`	`limactl ls --format='{{.SSHConfigFile}}' <实例>` 取路径
日常交互、VS Code Remote Development、第三方工具集成	方式二：`Include ~/.lima/*/ssh.config`	一次性配置，后续 `ssh lima-<实例>` 直接连
不支持配置文件的 SSH 客户端、嵌入式/精简环境	方式三：等价命令行参数	`limactl list --format '{{ .SSHLocalPort }}' <实例>` 取端口

实际使用时请注意：

三种方式都以 lima-<INSTANCE> 作为 SSH 用户名登录用户、以 127.0.0.1:<SSHLocalPort> 作为目标地址，端口为动态分配，实例重建或重启后可能变化，务必实时查询；
方式二的 Include 通配符会覆盖 ~/.lima/ 下所有实例，若存在不想要的主机条目，可在 ~/.ssh/config 中后续追加同名 Host 块覆盖，或对实例使用更具体的别名管理；
若需要在 Windows 上使用，仓库在 pkg/sshutil/sshutil.go 中对 SSH 可执行文件的探测做了专门处理（pickCompleteSSHOnWindows），会优先选择同时包含 scp.exe 与 ssh-keygen.exe 的完整 OpenSSH 安装（如 %SystemRoot%\System32\OpenSSH），避免 MinGit 等不完整安装导致 limactl create、limactl copy 失败——这说明"能跑通 ssh"与"能跑通 Lima 全流程"并不等价，连接异常时可优先检查 ssh 工具链的完整性。