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