蔡振原同事的项目在 CI 上跑了两年都没问题，上周突然一连挂了好几次，日志里只有一行红字：Host key verification failed. 一开始大家以为是 GitHub 服务抽风，重跑了几次照样崩，最后我帮他查了一圈才发现，问题根本不在网络，也不在 token，而是那台新换的构建机上 known_hosts 里躺着一份过期指纹。
这种经历应该不少人都有过。本地 npm install 本来是最日常不过的操作，突然有一天依赖装到一半，终端蹦出一句 Host key verification failed，后面还跟着 fatal: Could not read from remote repository. 很多人第一反应就是删 node_modules、清缓存、重新 clone，结果一顿操作猛如虎，错误原封不动。其实这个报错和 npm、和 node_modules 都没关系，真正在报错的是底层 git 调用，而 git 背后又是 SSH 在拒绝连接。文章会把这个链路彻底讲透，分别覆盖本地开发机、CI/Docker 自动化环境、以及依赖源配置三种最常见场景，最后给出一套完整的定位排查过程。无论你是普通前端项目装不上依赖，还是执行 npm install -g @openai/codex 这类全局工具时被卡住，应该都能从这里找到答案。
1. 先看报错长什么样：本地、容器、陈旧指纹三种现场
Host key verification failed 只是一句结果，不是原因。要处理它，第一步应该是看报错出现的上下文，因为不同环境下它的“长相”不一样，处理路径也完全不一样。
1.1 本地开发机最常见的完整错误段
本地终端里执行 npm install 时，如果某个依赖需要走 SSH，通常不会只报一行，而是一整段：
text复制npm ERR! Error while executing:
npm ERR! /usr/bin/git ls-remote git+ssh://git@github.com/company/private-repo.git HEAD
npm ERR!
npm ERR! Host key verification failed.
npm ERR! fatal: Could not read from remote repository.
npm ERR!
npm ERR! Please make sure you have the correct access rights
npm ERR! and the repository exists.
注意这里有个容易被忽视的细节：npm 真正执行的是 git ls-remote，不是直接 git clone。npm 在解析版本依赖时，需要先知道远端仓库有哪些 tag、哪个分支是默认分支，所以它会调用 git 去远端“看一眼”。这一眼就是 SSH 连接，也是报错开始的地方。
很多人这时候会下意识地执行 rm -rf node_modules && npm install，或者干脆把整个仓库重新 clone 一遍。但这不是依赖损坏，node_modules 里没有任何东西能修复 SSH 连接问题。只要 package-lock 还锁着同一个 git 依赖源，重装一百次也会在同一个位置报同样的错。
1.2 CI 与全新容器里的另一种形态
在 CI 或 Docker 构建环境里，报错会更“干瘪”。因为没有交互式终端，SSH 客户端无法弹出确认指纹的提示，所以你不会看到 Are you sure you want to continue connecting 这类询问，而是直接失败：
text复制npm ERR! code 128
npm ERR! command failed
npm ERR! command git ls-remote git+ssh://git@github.com/company/private-repo.git HEAD
npm ERR! Host key verification failed.
如果是在 GitHub Actions、GitLab CI、Jenkins Pipeline 这类平台里，错误日志往往被折叠在某个 step 中，只显示最后几行。这时候判断依据就不是“有没有弹窗”，而是“known_hosts 文件到底存不存在、有没有对应的 host 记录”。
1.3 容易被当成网络问题的陈旧指纹
第三种现场最隐蔽：本地之前一切正常，某天开始报错，而且不是首次连接。这种场景通常出在远端服务器重置过、更换过 SSH host key，或你手动清理过 ~/.ssh/known_hosts 后残留了旧记录。SSH 客户端发现 known_hosts 里存的主机指纹和服务器当前返回的指纹对不上，就会拒绝连接。
它的报错文本和第一种几乎一样，但处理方式完全不同：不能简单地把新指纹追加进 known_hosts，因为旧记录还在，SSH 会认为存在“中间人攻击”风险，仍然拒绝连接。必须先把旧指纹删掉，再写入新指纹。
判断到底是哪种现场，有个很实用的口诀：看报错之前有没有 REMOTE HOST IDENTIFICATION HAS CHANGED 警告，有就是指纹变更；没有就是首次连接或 known_hosts 缺失。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 真正的原因：npm install 是怎么被 SSH 的 host key 挡下的
这一节把机制讲清楚。理解了机制之后，你会发现网上大量“重新生成 SSH key”“把公钥加到 Git 平台”之类的回答，其实都没打在点上。
2.1 触发链路：从 package.json 到 git ls-remote
先看一个典型的会触发 SSH 的依赖写法：
json复制{
"dependencies": {
"internal-tool": "git+ssh://git@github.com/company/internal-tool.git#v1.2.0"
}
}
git+ssh:// 开头的 URL 已经说明一切：npm 要拿到这个包，必须先通过 SSH 连上 GitHub。然而 npm 自己并不处理 SSH 协议，它只是一个包管理器，真正干活的是 git。
当 npm 开始解析依赖树时，遇到这种 git 依赖，它会：
- 调用
git ls-remote <repository-url>获取远端引用； - 根据返回的 commit/tag 确定该安装哪个版本；
- 把这个 co