npm install卡在fetchMetadata或超时，主因是私有包仓库未正确配置导致registry路由错误；应通过@scope:registry按作用域指定私有源，配合_authToken认证，并分层配置国内镜像与私有源以兼顾速度与兼容性。
为什么 npm install 会卡在
或超时？
私有包仓库未正确配置时，
会默认走官方 registry（
），但私有包在那根本不存在。npm 会反复重试、降级协议、甚至 fallback 到旧版解析逻辑，表现为卡在
、
等阶段，或报
/
。这不是网络问题，而是 registry 路由错误。
检查当前 registry：运行
，确认不是
私有包名必须符合 scope 规则（如
），否则 npm 不会自动路由到 scoped registry
若混用 public 和 private 包，需同时配置
+
，否则非 scoped 包也会被错误转发
如何为 scoped 包单独指定私有 registry？
不要全局改
，否则 public 包（如
）也会被发往私有仓——多数私有仓不代理 public 包，直接 404。正确做法是按 scope 绑定 registry：
是关键配置项，告诉 npm 所有
包都走这个地址
认证信息必须写成
格式，不能用
—— 后者会被忽略
token 建议存入
并设权限
，避免泄漏
如何让 npm 同时加速 public 包下载并兼容私有包？
国内直接连
极慢，但换镜像（如
）后，私有包又会 404。解法是分层 registry 配置：
全局
设为国内镜像，覆盖所有未被 scope 拦截的包（即 non-scoped 包）
优先级更高，scoped 包强制走私有地址，不受全局 registry 影响
确保每次请求都带 token，避免私有仓因无 auth header 拒绝请求
注意：某些私有仓（如 Nexus、Verdaccio）要求 token 放在
header，此时需用
（base64 编码后的
）而非
CI/CD 中如何安全注入 registry 配置？
本地
可能被 git 提交误传，CI 环境更不能硬编码 token。推荐运行时动态写入：
CI 脚本中用
追加，避免覆盖已有配置（比如 global registry）
token 必须通过 CI secret 注入（如 GitHub Actions 的
），严禁明文写死
Verdaccio 用户注意：其默认允许匿名读取，但若开启
，则
和
都需完整 auth，此时
必须存在且有效
私有 registry 的路径匹配是前缀式且区分大小写的，
和
被视为不同 scope；token 过期、scope 拼错、registry 地址末尾多了一个
，都会导致静默失败——建议先用
验证连通性，再跑 install。
fetchMetadatanpm installhttps://registry.npmjs.org/fetchMetadataresolveWithNewModule404 Not FoundETIMEDOUTnpm config get registryhttps://registry.npmjs.org/@myorg/utilsregistry@myorg:registryregistrylodashnpm config set @myorg:registry https://npm.myorg.com/
npm config set //npm.myorg.com/:_authToken "your-token-here"@myorg:registry@myorg/*///:_authToken @myorg:_authToken~/.npmrcchmod 600 ~/.npmrcregistry.npmjs.orghttps://registry.npmmirror.comnpm config set registry https://registry.npmmirror.com
npm config set @myorg:registry https://npm.myorg.com
npm config set @myorg:always-auth trueregistry@myorg:registry@myorg:always-auth trueAuthorization_authusername:password_authToken.npmrcecho "@myorg:registry=https://npm.myorg.com" >> .npmrc
echo "//npm.myorg.com/:_authToken=${NPM_TOKEN}" >> .npmrcecho${{ secrets.NPM_TOKEN }}access: $authenticatednpm publishinstall_authToken@MyOrg@myorg/npm view @myorg/utils