npm/yarn 注册表（Registry）与 .npmrc 配置指南

今天安装第三方库遇到一个报错，我一直以为是网络问题，原来是它......

javascript 复制代码

yarn add xxxx
[1/5] 🔍  Validating package.json...
[2/5] 🔍  Resolving packages...
info There appears to be trouble with the npm registry (returned undefined). Retrying...
info There appears to be trouble with the npm registry (returned undefined). Retrying...
info There appears to be trouble with the npm registry (returned undefined). Retrying...
info There appears to be trouble with the npm registry (returned undefined). Retrying...

一、什么是 Registry？

Registry （注册表）就是 npm 包的"仓库地址"。当你执行 yarn add xxx 或 npm install xxx 时，包管理器会向 Registry 发送请求，查找并下载对应的包。

常见的 Registry 地址：

Registry	地址	说明
npm 官方	`https://registry.npmjs.org/`	全球最大的公共包仓库
npmmirror 淘宝镜像	`https://registry.npmmirror.com/`	国内镜像，同步官方，速度更快
私有源	各公司自建	如 Verdaccio、Nexus、GitHub Packages 等

二、.npmrc 是什么？

.npmrc 是 npm/yarn 的配置文件，用于控制包管理器的各种行为，其中最常见的就是指定 Registry 地址。

.npmrc 的本质就是一层层配置覆盖机制。

三、.npmrc 的四个层级（优先级从高到低）

scss 复制代码

优先级高 ────────────────────────────────────────── 优先级低

项目级 .npmrc  >  用户级 ~/.npmrc  >  全局级 $PREFIX/etc/npmrc  >  内置默认
  (本项目)        (本机所有项目)        (本机所有用户)            (兜底)

1. 项目级（最高优先级）

bash 复制代码

<项目根目录>/.npmrc

只影响当前这一个项目
可以和代码一起提交到 Git，团队成员共享配置
这是最推荐的管理方式

2. 用户级

bash 复制代码

~/.npmrc

影响本机当前用户的所有项目
适合配置个人偏好，如 init-author-name、init-license 等
⚠️ 不要在这里写 Registry 配置，容易污染其他项目

3. 全局级

bash 复制代码

$PREFIX/etc/npmrc

影响本机所有用户的所有项目
极少使用

4. 内置默认

npm 自带的默认配置
什么都不配时，Registry 默认就是 https://registry.npmjs.org/

四、查看你当前的配置

bash 复制代码

# 查看当前生效的 registry
npm config get registry
yarn config get registry

# 查看所有配置及其来源
npm config list

五、Scope 注册表：同时使用多个源

这是本文的核心知识点。一个项目里，有些包来自公司私有源，有些包来自 npm 官方，怎么让它们共存？

答案就是 Scope（作用域）注册表。

什么是 Scope？

npm 包名中 @ 开头的那部分就叫 Scope，比如：

less 复制代码

@ant-design/react-native     → scope 是 @ant-design
@react-navigation/native      → scope 是 @react-navigation
@hnao/swagger2ts             → scope 是 @hnao
@d11/react-native-fast-image  → scope 是 @d11

配置方式

在项目根目录的 .npmrc 中：

ruby 复制代码

# 默认源：所有没被特殊处理的包都走这里
registry=https://registry.npmjs.org/

# scope 源：只有 @hnao 前缀的包走公司私有源
@hnao:registry=http://npm.hz5g.cn/

# 可以配置多个 scope
# @myscope:registry=http://my-private-registry.com/

工作原理

sql 复制代码

yarn add react-native-svg          → 没有 @scope → 走默认源 registry.npmjs.org
yarn add @d11/react-native-fast-image  → @d11 没配特殊规则 → 走默认源
yarn add @hnao/swagger2ts          → @hnao 配了规则 → 走 npm.hz5g.cn

多个 scope 示例

ini 复制代码

registry=https://registry.npmjs.org/
@company-a:registry=https://npm.company-a.com/
@company-b:registry=https://npm.company-b.com/

六、真实场景：我们遇到的问题

背景

电脑上 ~/.npmrc（用户级）把 registry 设成了公司内部源 http://npm.hz5g.cn/
这个源可能没有同步某些公共包，或者不稳定

现象

bash 复制代码

$ yarn add @d11/react-native-fast-image
info There appears to be trouble with the npm registry (returned undefined). Retrying...

Yarn 向公司源请求 @d11/react-native-fast-image，但源返回了空响应，重试三次后失败。

解决

创建项目级 .npmrc，覆盖用户级配置：

ruby 复制代码

registry=https://registry.npmjs.org/
@hnao:registry=http://npm.hz5g.cn/

默认走官方源 → 公共包正常下载
@hnao 走公司源 → 私有包也能下载
互不干扰

七、最佳实践总结

做法	推荐？	说明
把 registry 写在项目 `.npmrc`	✅ 推荐	项目隔离，可提交 Git，团队共享
把 registry 写在 `~/.npmrc`	❌ 不推荐	会影响本机所有项目
用 scope 区分公私源	✅ 推荐	精准控制，避免切来切去
每次手动 `yarn config set registry`	❌ 不推荐	容易忘记切回来，出问题排查困难
把 `.npmrc` 提交到 Git	✅ 推荐	团队其他成员不用再配置

八、常见命令速查

bash 复制代码

# 查看当前 registry
npm config get registry

# 临时切换 registry 装包（不影响配置）
npm install xxx --registry=https://registry.npmjs.org/

# 查看所有 npm 配置
npm config list

# 查看某个配置的来源（项目/user/global）
npm config list -l

九、延伸阅读

除了 registry，.npmrc 还可以配置 proxy、https-proxy（代理）、always-auth（认证）、save-exact（精确版本）等
私有源通常需要认证，可以在 .npmrc 中配置 //registry.xxx.com/:_authToken=xxx
.yarnrc 是 yarn v1 的额外配置文件，yarn v2+（Berry）使用 .yarnrc.yml
package-lock.json / yarn.lock 记录了每个包的实际下载源地址（resolved 字段），即使切源也不影响已锁定的版本