用 pnpm 装依赖装到怀疑人生，相信不少同学都经历过。我印象很深的一次，是在一台新配的 Ubuntu 机器上跑pnpm install，进度条卡在某个包上十分钟不动，最后直接抛了一个ERR_PNPM_FETCH_ETIMEDOUT。当时我下意识去查 Node 版本、网络连通性、DNS 解析，全都正常，最后才意识到问题出在 pnpm 默认的注册表走的是海外节点，国内网络环境延迟高、丢包多，连接根本撑不住。这种问题的解法其实很明确，把注册表指向国内镜像源就行。这篇文章记录我在 Ubuntu 上为 pnpm 切换国内镜像源的完整过程，包括背后的原因分析、三种配置方式的取舍、验证手段和常见坑，以及顺手能做的一些优化。无论你是刚入行的前端新人，还是在团队里负责基础环境的同学，这篇内容应该都有参考价值。
1. 为什么默认源在国内经常拉不动：一次 install 卡半天的根因
1.1 pnpm 默认的 registry 和它为什么慢
pnpm 默认的注册表地址是https://registry.npmjs.org，这是 npm 官方维护的全局注册中心。这个源本身很稳定、更新也及时，但它的服务器主要部署在海外，国内直连时数据包要跨越大段国际链路，中间经过大量路由节点、运营商出口设备和国际带宽瓶颈。你用家用宽带、小型机房或者国内云服务器访问时，能明显感觉到延迟偏高、带宽不足。我做过一个简单测试，在普通网络下用curl访问官方源的元数据接口，响应时间经常超过一秒，下载一个几十 MB 的依赖包时，丢包导致的重传会让人非常痛苦。
pnpm 在安装依赖时会向 registry 发起大量并发请求，每个包既要获取元数据又要下载 tarball 文件。如果网络质量不行，TCP 连接就会反复超时、重试、再超时，最终让整个pnpm install卡在某个包上很长时间。当时让我卡住的那个包只有两三 MB，按理说几秒钟就能下完，但因为连接迟迟建立不起来，重试机制把整个安装流程拖垮了。这类问题用pnpm install --verbose查看日志时，通常能看到大量ETIMEDOUT、socket hang up或ECONNREFUSED之类的记录，基本都属于网络层问题，而不是包本身出错。
1.2 国内镜像到底在做什么
国内镜像源的原理并不复杂：它们会定期从官方注册表同步全量元数据和文件，把数据放到国内服务器或 CDN 上，然后对外提供与 npm 协议兼容的接口。你把 registry 改成镜像地址后，pnpm 会向国内节点发起请求，网络往返距离大幅缩短，下载速度自然就上来了。这个过程对用户几乎是透明的，pnpm 不会感知到远端是官方源还是镜像，只需要保证接口协议一致即可。
目前常见的国内镜像源主要有两个：https://registry.npmmirror.com和https://mirrors.cloud.tencent.com/npm/。前者覆盖面广、同步频率高，官方发布新包后很快就能在镜像上看到，作为首选一般没有太大问题；后者在部分网络环境下访问也很稳定，可以作为备选。我自己的习惯是优先用 npmmirror，如果遇到某个包还没同步或者网络环境特殊，再切到另一个镜像试一次。
这里必须提一个容易忽略的前提：换源等于把依赖分发的信任交给第三方。虽然 pnpm 会通过 lockfile 里的integrity哈希做完整性校验，如果镜像本身被入侵或者被故意篡改，风险依然存在。所以在正式项目里，建议锁定依赖版本、定期检查 lockfile，同时关注镜像源是否有官方同步状态页面，一旦发现异常及时切换到备用源。
1.3 哪些信号出现时基本就该换源
不是所有场景都必须换源，但以下几条信号一旦出现，基本就可以认真考虑切换了：
pnpm install长时间卡在某个包，日志出现ETIMEDOUT、ECONNREFUSED、socket hang up- CI/CD 构建镜像时，每次拉取依赖都占据整个构建流程的大半时间
- 个人电脑或服务器部署在国内，网络出口对海外节点不友好
- 安装大型依赖树时，等待时间以小时计
如果你的网络环境本来就能顺畅访问官方源，不换也完全没有问题。换源只是让体验更好，不是一个硬性要求。理解这一点很重要，能避免你盲目跟随别人换源，结果在特殊网络环境下反而引入新的问题。
2. 换源前的环境检查与准备：先把底子摸清楚
2.1 确认 pnpm 的安装方式和版本
换源之前，先确认一下当前环境。在 Ubuntu 上运行：
node -v npm -v pnpm -vpnpm 的安装方式通常有三种：通过 npm 全局安装、通过 corepack 启用、通过官方二进制安装。不管哪种方式，配置逻辑在本质上是一样的。我建议先记录一下当前版本号，因为不同版本对配置文件的读取行为和默认参数处理有细微差别。比如早期版本会直接复用 npm 的~/.npmrc，新版本虽然也读取这个文件，但某些项目级配置的优先级处理会有变化。版本越老，遇到诡异配置问题的概率越高，有条件的话尽量升级到较新的稳定版本。
2.2 查看当前生效的 registry
在改动之前，必须知道自己当前实际用的是哪个源。运行：
pnpm config get registry正常情况下输出的是https://registry.npmjs.org/。如果你之前已经改过，这里会显示之前设置的地址。还可以用pnpm config list查看全部配置，这个命令会同时显示全局配置、用户配置以及环境变量覆盖的情况，非常直观。很多新手以为pnpm config get registry输出的就是全局配置文件里的值，其实它显示的是最终生效值，是各层配置合并后的结果。
我在这一步会额外留意pnpm config list输出里有没有globalconfig和userconfig两项路径。它们指向全局配置文件和用户配置文件的位置，Ubuntu 上常见的是/etc/npmrc和~/.npmrc这两个路径。搞清楚配置文件位置，后面排查问题时才知道去哪里看。
2.3 备份已有的 npmrc 文件
接下来是一个容易被忽略的步骤：备份。Ubuntu 上主要涉及两个文件：
- 用户级配置：
~/.npmrc - 项目级配置：项目根目录下的
.npmrc
切换镜像前先各自复制一份：
cp ~/.npmrc ~/.npmrc.bak.$(date +%Y%m%d)如果你在多个项目里工作，还要逐个检查项目根目录下有没有.npmrc，以及它是否被提交到 Git 仓库。备份的意义在于，万一新配置导致某些包拉不下来，你可以一键恢复之前的状态，不需要在排查问题时费力回忆原先写过什么。这个习惯后来帮了我一次大忙：某个镜像站曾经短暂出现过证书异常，我直接恢复备份切回官方源，全程没有影响手头开发工作。
2.4 理解 pnpm 的配置优先级
配置生效的优先级从高到低是：命令行参数 > 环境变量 > 项目.npmrc> 用户.npmrc> 全局.npmrc。这一点非常重要，因为很多人明明在全局配置了国内镜像，但到了某个项目里实际用到的还是别的源。项目自带的.npmrc完全可以覆盖用户和全局配置，带来的直观结果就是“我明明换过源，为什么还是慢”。
排查配置问题时，我通常会按上面这个优先级逐层检查，而不是只盯着pnpm config get registry的输出。否则很容易出现配置明明写对了，实际行为却完全不符合预期的困惑。
3. 三种镜像配置方式与适用场景：全局、项目、一条命令
3.1 全局配置：一条命令搞定所有项目
如果想让当前用户下的所有项目默认都走国内镜像，全局配置是最简单的：
pnpm config set registry https://registry.npmmirror.com --global这条命令会写入用户级~/.npmrc。之后不管在哪个项目里执行pnpm install，都会默认从新镜像拉取依赖，除非项目里有自己的配置做了覆盖。
全局配置适合的场景，主要是个人开发机，或者你对整台机器的网络环境有统一要求时。比如团队新配的 Ubuntu 开发机，统一设置国内镜像可以省去每个成员手动折腾的时间。但全局配置也有一个隐患：一旦你需要安装某些只有官方源才有的私有或实验性包，或者镜像同步出现延迟，全局改源反而会让问题变得隐蔽。我的做法是尽量保持全局配置简单，把需要精确控制的项目放到项目级配置里处理。
3.2 项目级配置：把镜像规则写进仓库
项目级的做法是在项目根目录创建或修改.npmrc文件：
registry=https://registry.npmmirror.com这种方式最大的好处是可持续维护和团队一致。把.npmrc提交到 Git 仓库后，所有成员拉取代码执行pnpm install时，都会自动使用相同的镜像源，避免出现“我这边能装上，你那边装不上”的争论。
需要注意，pnpm 读取项目.npmrc时，会与用户级配置合并，且项目配置优先级更高。如果你在全局设置了镜像 A，而项目里设置了镜像 B，最终使用的是镜像 B。所以项目级配置一定要反复确认，它不仅是加速手段，也决定了整个团队的依赖来源。对于多人协作的项目，我强烈建议用项目级配置，而不是把希望寄托在每个人各自的全局配置上。
3.3 临时切换：命令行参数与环境变量
有些时候，你只是想在一次操作里换个源试试，并不想留下任何配置，可以用命令行参数：
pnpm install --registry=https://registry.npmmirror.com或者通过环境变量实现：
export npm_config_registry=https://registry.npmmirror.com pnpm install环境变量的好处是只对当前 shell 或当前进程生效，不会写入任何配置文件，非常适合在 CI 脚本或 Docker 构建中使用。但要留意，环境变量的优先级高于项目.npmrc，如果 CI 环境里设置了镜像，仓库里的项目配置会被完全忽略。这个特性既是优点也是风险，用的时候要想清楚。
3.4 三种方式的对比与选择
| 配置方式 | 作用范围 | 持久性 | 是否跟随仓库 | 推荐场景 |
|---|---|---|---|---|
| 全局配置 | 当前用户所有项目 | 持久 | 否 | 个人开发机统一加速 |
| 项目配置 | 当前项目 | 持久 | 是 | 团队协作、多端一致 |
| 命令行参数 | 单次命令 | 临时 | 否 | 快速测试、偶尔换源 |
| 环境变量 | 当前 shell/进程 | 临时 | 否 | CI 脚本、Docker 构建 |
实际使用中我经常组合使用：全局保持一个默认源，正式项目里用项目.npmrc指定更稳定的镜像，CI 里再用环境变量覆盖成离构建机器最近的镜像节点。每一层都有明确的控制点，排起问题来也容易定位到底是谁覆盖了谁。
3.5 作用域注册表：让部分包走特殊源
如果项目依赖了某个特定作用域下的私有包，比如@company/xxx，可以这样配置：
@company:registry=https://registry.npmmirror.com这样只有@company作用域下的包会走指定源，其他包仍然使用默认 registry。这个功能在实际项目中很实用，尤其是混合使用公共依赖和内部依赖的时候。我在一个跨团队项目里，因为内部包托管在独立服务上，公共包希望走镜像加速，就是用作用域配置同时解决了两边需求，不需要为了某几个包把整个项目源切来切去。
4. 性能与一致性：切换镜像后，还有这些细节值得调
4.1 pnpm 的全局存储目录和镜像切换的关系
pnpm 和 npm、yarn 一个显著差异，是它采用内容寻址的全局存储机制。所有下载过的包会缓存在一个全局存储目录，项目里通过硬链接引用这些文件，不需要把每份依赖都完整复制进各项目的node_modules。Ubuntu 下默认存储路径一般是~/.local/share/pnpm/store。
切换镜像源后，这个存储依然有效。如果之前已经用官方源下载过某些包，换源后这些包会直接命中存储，不会重复下载，也不会因为镜像源不同而重新拉取。因为决定缓存命中的是包的内容哈希，不是下载源的地址。这一点很多人不了解，以为换源会导致整个缓存全部失效，白白删掉存储目录，反而浪费时间重新下载。
不过需要注意一个边界情况：如果同一个包在官方源和镜像上的 tarball 内容不完全一致，pnpm 会分别缓存不同内容。现实中这种情况极少见，但一旦遇到，存储体积会略微增加。处理方式也简单，确认是镜像同步异常后，切换到正常源再执行一次安装即可。
4.2 调整并发和超时参数
换了国内镜像后，网络延迟降低，pnpm 默认并发参数通常已经够用。但在某些极端情况下，比如公司网络出口对并发连接数有限制，或者镜像站本身负载较高，可以做一些针对性调优：
network-concurrency=16 child-concurrency=5 fetch-timeout=60000network-concurrency控制同时下载的并发数，默认是 16。如果带宽比较大，可以适当调到 32 或 48；如果经常遇到连接被拒，反而应该调低，避免触发镜像站限流。child-concurrency控制构建依赖时的并发进程数，默认是 5，调高会增加 CPU 压力，对大型项目未必是好事。fetch-timeout是请求超时时间，单位毫秒。国内镜像响应通常很快，一般不用改。但如果某些冷门包同步慢，适当调大能减少失败概率。
我调这些参数的原则是“小步试错”，每次只改一个配置项，然后观察完整 install 的耗时和失败率。同时改太多参数，出了问题根本分不清是哪个参数引起的。
4.3 确保 lockfile 的完整性校验一致
很多人换源后第一次执行pnpm install会遇到integrity校验失败。这往往不是镜像本身坏了，而是 lockfile 中记录的哈希和镜像提供的文件不一致，或者旧 lockfile 里的包版本引用到了镜像尚未同步的快照。处理方法是先看报错指向哪个包，如果只是个别包，用pnpm update <package>重新解析；如果大量报错，再考虑删除 node_modules 和 lockfile 重新生成。
在 CI 环境切换镜像时，我建议先确认 lockfile 能在目标镜像上恢复完整，再执行pnpm install --frozen-lockfile。直接硬跑很可能白等一场，日志最后全是校验失败的信息。这里要特别小心，团队成员分布在不同的网络环境，有些人用的是旧 lockfile，有些人已经更新了依赖，很容易出现明明镜像没问题却反复报哈希错误的情况。提前统一 lockfile 状态可以省掉很多沟通成本。
4.4 缓存与离线安装的妙用
国内镜像的一大好处是下载速度快，但网络并非永远稳定。可以提前用pnpm store add把关键依赖下载到本地存储，在网络不佳时使用--offline或--prefer-offline参数安装。这种方式在出差、通勤或者临时网络受限的场景下特别好用。我经常在酒店网络好的时候跑一次完整 install，把整个依赖树都放进存储，第二天在高铁上继续开发时，基本上不会因为网络问题卡住。
5. 验证与排错：配置完成后不能直接信任它
5.1 基本验证步骤
换完源之后，先跑一个简单的验证流程：
pnpm config get registry确认输出是你设置的镜像地址。然后随便拉一个包做测试：
mkdir -p /tmp/pnpm-test && cd /tmp/pnpm-test pnpm init pnpm add left-pad如果这个命令能在几秒内完成，说明镜像配置基本没问题。我建议在独立目录测试，不要直接拿正式项目验证，否则项目本身的依赖树太复杂，出了问题分不清是配置原因还是网络问题。
5.2 常见错误现象和应对
| 错误现象 | 常见原因 | 处理建议 |
|---|---|---|
ERR_PNPM_FETCH_404 | 镜像上还没有同步某个包的最新版本 | 切换备用镜像，或等待同步后重试 |
ERR_PNPM_FETCH_ETIMEDOUT | 网络连接镜像超时 | 换备用镜像，检查代理设置 |
integrity checksum failed | lockfile 与镜像文件哈希不一致 | 更新对应包，或重建 lockfile |
UNABLE_TO_VERIFY_LEAF_SIGNATURE | 镜像证书链问题或系统缺少根证书 | 检查系统时间，更新 ca-certificates |
| 配置了但没生效 | 项目.npmrc覆盖了全局配置 | 用pnpm config list确认最终生效层级 |
表格里这几类问题基本覆盖了换源过程中最常见的坑。其中ERR_PNPM_FETCH_404最容易迷惑人，因为看起来像包不存在，但实际只是镜像还没同步。遇到这种情况别急着改项目，先到官方源查一下这个包是否存在，再判断是镜像延迟还是项目配置错误。
5.3 排查配置覆盖问题的技巧
有一次我在某个项目里换了镜像，但pnpm install依然慢得离谱。用pnpm config get registry查看，显示的却是全局的官方源地址。我以为是命令没生效，反复设置了好几遍，结果都一样。最后仔细看项目根目录才发现，.npmrc里有一行registry=https://registry.npmjs.org/，是项目早期为了其他目的写的。这种隐蔽的覆盖问题在实际开发中非常常见，所以排查时要同时看全局配置、用户配置、项目配置和环境变量四个层面。
排查步骤：
- 执行
pnpm config list查看所有生效配置。 - 检查项目根目录
.npmrc是否包含 registry 项。 - 检查用户
~/.npmrc是否包含 registry 项。 - 检查环境变量里是否有
npm_config_registry。
把这几层都看完，基本就能定位是哪里把配置覆盖掉了。实际工作中我遇到过最离谱的情况，是 CI 机器的全局 npmrc 里残留了一个测试用的 registry 地址，导致所有项目在 CI 上都走了异常源，排查了很久才发现是机器级别的配置污染。
5.4 从镜像安全切回官方源
如果后续不想再用国内镜像，恢复也很简单：
pnpm config set registry https://registry.npmjs.org --global项目级的话，直接移除项目.npmrc里的 registry 行即可。有备份的话更方便，直接执行cp ~/.npmrc.bak.xxx ~/.npmrc就能恢复。切换回官方源后，之前从镜像下载的缓存仍然可以使用，不会失效，只是后续新依赖会恢复官方源的速度。这里分享一个真实经历：我曾经把全局 registry 从镜像改回官方源，结果忘了项目里有一个私有包版本很旧，官方源已经把它移除了，lockfile 又锁死了这个版本，导致pnpm install始终失败。最后在项目.npmrc里临时加了一行作用域配置，只让这个私有作用域走镜像，其余包用官方源，问题才解决。这件事让我更加坚定“全局配置尽量简单、项目配置精确控制”的原则。
换源这件事本身不复杂，但背后的核心是平衡网络环境适配和依赖分发可靠性。我在实际操作中的体会是：全局配置用来兜底，项目配置用来定规则，CI 里用环境变量做临时调整，层次分明之后，排查问题会轻松很多。如果你也正在被 pnpm 下载速度折磨，不妨先备份好现有配置，再按文章里的方法试一次。切换镜像后记得跑一遍完整安装流程，确认没有报错再继续开发，后面基本不会再有什么意外。
