前端项目启动第一步往往是安装依赖，但 npm、pnpm、yarn 依赖树复杂，包数量多，还可能引用 GitHub 仓库、二进制预编译包、Electron、Playwright、Sharp、esbuild、node-sass 等额外下载资源。网络稍微不稳定，就会出现 install 卡住、fetch failed、ETIMEDOUT、ECONNRESET、node-gyp 失败等问题。
排查这类问题时，不要只盯 npm registry。依赖安装过程可能访问多个域名和 CDN，也可能因为 lockfile 冲突、缓存损坏、Node 版本不匹配、代理变量配置错误而失败。下面按开发者实际排查路径整理。
- 区分 registry 下载慢、GitHub 依赖慢、二进制包慢和本地编译慢。
- 检查 Node 版本、lockfile、缓存、包管理器版本和磁盘权限。
- 排查 DNS、TLS、CDN、代理变量和 VPN 加速链路。
- 把前端依赖安装放到 Docker 或 CI 时，要单独检查容器网络。
一、不同卡顿点对应不同问题
| 表现 | 可能原因 | 优先排查 |
|---|---|---|
| Resolving 很久 | 依赖树复杂、lockfile 冲突 | 包管理器版本、lockfile、workspace 配置 |
| Fetching 很慢 | Registry 或 CDN 连接慢 | DNS、TLS、下载源、VPN 线路 |
| GitHub 依赖超时 | 依赖直接指向 Git 仓库 | GitHub 链路、SSH/HTTPS、企业网络策略 |
| node-gyp 失败 | 二进制包没下到，转为本地编译 | Python、编译工具、预编译包下载地址 |
| CI 里慢，本地正常 | CI 网络、缓存、容器 DNS 不同 | CI 缓存、Runner 区域、Docker 网络 |
二、先确认项目和包管理器状态
- 确认 Node 版本和项目要求一致，避免安装阶段触发不必要编译。
- 不要混用 package-lock.json、pnpm-lock.yaml、yarn.lock。
- 清理明显损坏的缓存，再重新安装，不要长期依赖半坏缓存。
- 确认 workspace、monorepo、private package 配置正确。
- 观察卡住的包名，判断是普通依赖、GitHub 依赖还是二进制包。
三、二进制包下载失败会变成本地编译
Sharp、esbuild、Playwright、Electron、node-sass、sqlite3 等包经常需要下载预编译二进制文件。如果这些文件下载失败，安装脚本可能会尝试本地编译，导致时间更长、错误更多。此时日志里往往会出现 node-gyp、prebuild、download failed、binary not found 等关键词。
重点观察日志关键词： ETIMEDOUT ECONNRESET fetch failed node-gyp prebuild-install download binary GitHub release postinstall
四、Docker 和 CI 里的 npm 慢要单独看
很多团队把 npm install 放进 Docker build 或 GitHub Actions。此时网络环境已经不是你的本地电脑，宿主机 VPN、DNS 或代理设置不一定会自动传入容器。CI Runner 所在区域、缓存策略和并发任务，也会让安装速度差异很大。
优先检查 Docker build 阶段是否能访问同样的 registry、GitHub 和二进制包地址。必要时把依赖安装、构建、运行拆成不同层，并开启包管理器缓存，减少每次从零下载。
五、稳如狗适合哪些前端开发场景
稳如狗加速器适合需要稳定访问 npm、GitHub、Docker、Playwright 浏览器包、Electron 二进制包、AI SDK 和海外技术文档的前端开发者。稳定的 VPN 加速链路可以减少依赖下载超时、GitHub Release 断连、postinstall 脚本失败和 CI 构建重试。
六、推荐排查顺序
npm / pnpm / yarn 慢排查： 1. 看日志卡在 resolving、fetching、postinstall 还是 node-gyp 2. 检查 Node 版本、lockfile、包管理器版本和缓存 3. 找出具体慢的包名和下载地址 4. 区分 registry、GitHub Release、Git 依赖、二进制包 5. 对比本地、Docker、CI 的网络表现 6. 多个海外开发资源都慢时，优化 VPN 加速线路