前端项目安装依赖时出现超时、ECONNRESET或证书错误，很多人第一反应是换仓库。实际排查中，仓库地址和代理是两条不同的链路：仓库决定请求发往哪里，代理决定请求如何到达那里。npm、pnpm和Yarn又可能读取不同层级的配置，必须先把配置来源理清。
一、先确认失败发生在哪一步
先保留完整但已脱敏的错误信息。域名无法解析通常先查DNS；连接超时要查路由、代理地址和防火墙；返回407是代理认证问题；TLS证书错误则应查时间、证书链与企业网络检查。不要把所有错误都归结为“仓库慢”。
通用错误码可对照代理407、502、503、504分层排查。
二、代理配置和registry分别控制什么
| 配置 | 作用 | 常见误区 |
|---|---|---|
| registry | 指定包元数据和压缩包仓库 | 更换仓库不等于启用代理 |
| proxy | 处理HTTP请求 | 不保证覆盖所有HTTPS场景 |
| https-proxy | 处理HTTPS目标请求 | 代理地址本身仍可能写成http:// |
| HTTP_PROXY/HTTPS_PROXY | 供支持环境变量的程序读取 | 不同版本和子进程行为可能不同 |
| NO_PROXY | 让指定目标绕过代理 | 匹配语法并不完全统一 |
三、npm怎么检查当前配置
先用npm config get proxy、npm config get https-proxy和npm config get registry查看结果，再用npm config list确认配置来自用户级、全局还是项目目录。设置时可使用npm config set proxy http://proxy.example:8080，HTTPS目标通常还需设置https-proxy。
如果代理需要账号密码，不要把真实凭据写入仓库中的.npmrc。配置文件可能进入版本控制、构建日志或镜像层，优先使用CI秘密变量或权限受限的用户级配置。
四、pnpm为什么看起来与npm相似
pnpm沿用不少npm风格的配置键，但安装过程还涉及内容寻址存储、工作区和独立缓存。出现问题时，应同时记录pnpm版本、配置来源、仓库地址和失败的实际下载域名。仅验证首页能打开，不能证明压缩包、审计接口和重定向目标都可达。
五、Yarn要先分清大版本
Yarn Classic与较新的Yarn版本在配置文件和命令上存在差异。不要从旧教程复制命令后直接判断工具不支持代理。先运行yarn --version，再查该版本的配置输出，并检查项目中的.yarnrc或.yarnrc.yml。团队项目应固定包管理器和版本，避免每台机器读取不同规则。
六、浏览器能打开，为什么安装仍失败
- 浏览器使用系统代理，Node进程使用环境变量或工具配置；
- 浏览器已登录，包管理器访问的是匿名下载或令牌接口；
- 仓库页面和压缩包托管在不同域名；
- 终端与IDE、CI服务的运行用户不同；
- 已有连接池或DNS缓存尚未更新。
Node运行时的代理边界可参考Node.js fetch与Undici代理配置。
七、证书错误不要靠关闭校验解决
若错误包含SELF_SIGNED_CERT_IN_CHAIN或证书颁发者不受信任，应确认代理是否进行了受控TLS检查、根证书是否由管理员正确分发、Node运行时是否信任该证书，以及目标域名是否匹配。长期关闭SSL校验会失去服务端身份验证。
证书排查顺序见HTTPS代理证书错误排查。
八、推荐的验证顺序
- 记录工具版本、Node版本和执行用户；
- 查看registry、proxy、https-proxy及相关环境变量；
- 从错误中提取实际目标域名和状态码；
- 用同一用户、同一终端执行最小安装测试；
- 在授权环境验证代理出口与证书链；
- 再进入CI或容器，比较环境差异；
- 测试完成后清理临时凭据与项目级配置。
九、一个容易忽略的清理动作
排障时临时写入的代理配置，常在问题解决后留在用户目录，几周后换节点才再次暴露。应记录修改过的配置层级，使用对应的删除命令恢复，并重新运行配置查询确认没有旧地址。对团队环境，最好把代理配置纳入变更记录，而不是靠口头交接。
十、结论
npm、pnpm和Yarn代理问题的关键，不是多试几个命令，而是区分仓库、代理、运行用户、工具版本与证书信任。用同一环境做最小验证，再逐层恢复工作区和CI，通常比反复切换镜像更快定位原因。
