npm/pip 装包太慢？国内镜像源配置与代理方案完整指南

Q: 换了 npmmirror 之后 package-lock.json 里的地址会变吗？

会。lockfile 的 resolved 字段会记录镜像地址，团队协作时建议在项目根目录提交 .npmrc 统一源，避免成员间 lockfile 互相覆盖。

Q: Docker 构建镜像时怎么用国内源？

在 Dockerfile 中显式设置即可： dockerfile RUN npm config set registry https://registry.npmmirror.com RUN pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple 顺带一提，Docker Hub 本身在国内拉取也很慢，解法参考《Docker Hub 拉取镜像慢？国内加速完整方案》。

npm install 卡在 idealTree 一动不动五分钟；pip install torch 进度条显示 10KB/s，预计还剩 6 个小时。这两个场景，几乎是每个在中国大陆写代码的前端和 Python 开发者的日常。

直答速览：装包慢的解法分两层——

换国内镜像源（免费，覆盖 90% 的日常场景）：npm 用 registry.npmmirror.com（原淘宝源），pip 用清华 TUNA 或阿里云镜像；
代理/VPN（覆盖剩下 10% 镜像无能为力的场景）：npm publish、git 依赖、GitHub Releases 二进制、私有包等必须直连官方源的操作。

下面按 npm、pip 分别给出可直接复制的命令，最后重点讲清楚哪些场景换源没用、该怎么办。

为什么 npm install 和 pip install 这么慢？

npm 官方 registry（registry.npmjs.org）和 PyPI 官方源（pypi.org）的服务器与 CDN 节点都在海外。从中国大陆直连时：

国际出口链路拥挤：请求要挤过有限的国际出口带宽，高峰期丢包率高，TCP 遇到丢包就自动降速；
CDN 节点不在境内：npm 和 PyPI 使用的 CDN 在大陆没有可用节点，静态资源要跨洋传输；
一次安装 = 成百上千个请求：一个中型前端项目 node_modules 里可能有上千个包，每个包都要走一遍慢速链路，元数据请求的高延迟被成倍放大——这就是 idealTree 阶段（npm 解析依赖树、批量请求包元数据）卡住的根本原因。

镜像源的原理很简单：国内服务器定时从官方源同步全量包，你就近下载，速度通常能从几十 KB/s 提升到 10MB/s 以上。

npm 部分：换源到 npmmirror

npmmirror（registry.npmmirror.com）是阿里维护的 npm 全量镜像，即原来的”淘宝源”，每 10 分钟与官方同步一次，是目前最稳定的 npm 国内镜像。

方法一：命令行永久换源（推荐）

# 设置镜像源
npm config set registry https://registry.npmmirror.com

# 验证是否生效
npm config get registry
# 应输出：https://registry.npmmirror.com

之后所有 npm install 都会走国内镜像，无需其他改动。

方法二：直接编辑 .npmrc

npm config set 本质上就是在写 ~/.npmrc 文件。你也可以手动编辑：

# ~/.npmrc
registry=https://registry.npmmirror.com

如果只想让某个项目走镜像（比如公司项目有自己的私有源），在项目根目录放一个 .npmrc 即可，项目级配置优先于用户级。

方法三：单次临时使用

npm install --registry=https://registry.npmmirror.com

pnpm / yarn 同理

# pnpm
pnpm config set registry https://registry.npmmirror.com

# yarn (v1)
yarn config set registry https://registry.npmmirror.com

验证效果与还原

# 测试：装一个小包看速度
npm install lodash --loglevel=http

# 还原为官方源（发包前必须做，见下文）
npm config set registry https://registry.npmjs.org

注意：老教程里的 registry.npm.taobao.org 域名已停止解析，.npmrc 里若还是旧地址会报 ETIMEDOUT 或证书错误，请更新为 registry.npmmirror.com。

pip 部分：换源到清华 TUNA 或阿里云

Python 这边最常用的两个镜像，都是全量镜像、同步及时，任选其一即可（教育网环境清华更快，云服务器上阿里云更稳）：

清华 TUNA：https://pypi.tuna.tsinghua.edu.cn/simple
阿里云：https://mirrors.aliyun.com/pypi/simple/

方法一：-i 参数临时使用

pip install requests -i https://pypi.tuna.tsinghua.edu.cn/simple

适合偶尔用一次，或在 CI 脚本里显式指定。

方法二：pip config 永久配置（推荐）

pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

# 验证
pip config list
# 应输出：global.index-url='https://pypi.tuna.tsinghua.edu.cn/simple'

方法三：手动编辑配置文件

pip config 写入的配置文件路径因系统而异，也可以直接手动创建：

系统	路径
Linux / macOS	`~/.config/pip/pip.conf`（旧版为 `~/.pip/pip.conf`）
Windows	`%APPDATA%\pip\pip.ini`

文件内容：

[global]
index-url = https://pypi.tuna.tsinghua.edu.cn/simple

还原官方源

pip config unset global.index-url

conda 用户同理：修改 ~/.condarc 指向清华镜像的 anaconda 频道即可；conda 环境里用 pip 装包仍走上面的 pip 镜像配置，两者互不影响。

关键章节：哪些场景换源也救不了？

镜像只同步公开包的下载这一件事。以下场景绕不开官方源或 GitHub，换源无效，这也是很多人”明明换了源还是卡”的真正原因：

发布包、登录账号、管理 token 这类写操作，镜像站根本不提供。如果你在换源状态下执行 npm publish，要么直接报错，要么发到错误的地方。发包前必须切回官方源：

npm config set registry https://registry.npmjs.org
npm publish

而 registry.npmjs.org 从国内直连本身就慢且不稳定，publish 超时失败是常事。

2. 依赖 GitHub 直链的包

很多包在 npm install 的 postinstall 阶段会从 GitHub Releases 下载预编译二进制——典型如 node-gyp 编译链、老项目里的 node-sass、electron、playwright 的浏览器内核等。包本体从镜像下载得飞快，然后卡死在从 github.com 拉二进制这一步。部分知名包 npmmirror 提供了二进制镜像（可通过环境变量如 ELECTRON_MIRROR 指定），但长尾包没有。

3. pip 安装 GitHub 上的包

pip install git+https://github.com/user/repo.git

这条命令根本不经过 PyPI，而是直接 git clone GitHub 仓库——镜像源配置对它完全不起作用。AI/ML 领域大量前沿库（论文配套代码、还没发版的 dev 分支）只能这样装。同理，package.json 里的 git 依赖（"foo": "github:user/repo"）也是直连 GitHub。

4. 私有 scope 包与私有 PyPI 仓库

公司内部的 @yourcompany/xxx 私有包托管在官方 registry 或 GitHub Packages 上时，镜像站无权同步，必须直连认证下载。

这些场景的共同点：必须和官方源 / GitHub 建立稳定直连，唯一的解法是代理或 VPN。 但如果开了全局 VPN，国内镜像反而可能绕远变慢——理想状态是”分场景走不同线路”。JetStream VPN 的智能分流正是为这种混合场景设计的：npm/PyPI 官方源、GitHub、GitHub Releases 等海外域名自动走低延迟 VPN 节点，而 npmmirror、清华 TUNA 等国内镜像流量自动直连不绕路。配好一次之后，npm publish、pip install git+https://... 和日常镜像装包可以共存，不需要来回开关代理。下载 JetStream 后开启智能分流模式即可。

如果你被 GitHub 克隆慢的问题困扰得更深，可以看这篇专门的指南：《GitHub 在中国访问慢？完整加速方案》。

方案对比总结

场景	换镜像源	代理/VPN
日常 `npm install` / `pip install` 公开包	✅ 首选，免费且快	可用但没必要
`npm publish` / `npm login`	❌ 无效	✅ 必需
git 依赖 / `pip install git+https://...`	❌ 无效	✅ 必需
postinstall 拉 GitHub Releases 二进制	⚠️ 部分包有二进制镜像	✅ 通用解法
私有 scope 包 / 私有源	❌ 无效	✅ 必需
刚发布几分钟的新版本包	⚠️ 镜像有同步延迟	✅ 直连无延迟

推荐组合：镜像源作为默认配置常年开着，JetStream 智能分流负责兜底官方源和 GitHub 流量——两者互不冲突，一次配置长期受益。

常见问题（FAQ）

换了 npmmirror 之后 package-lock.json 里的地址会变吗？

会。lockfile 的 resolved 字段会记录镜像地址，团队协作时建议在项目根目录提交 .npmrc 统一源，避免成员间 lockfile 互相覆盖。

镜像上的包安全吗？和官方一致吗？

npmmirror 和清华 TUNA 都是从官方源自动同步的完整副本，包的 tarball 校验和（integrity）与官方一致，npm/pip 安装时会自动校验，无需担心内容被篡改。唯一的区别是有几分钟到几小时的同步延迟。

为什么换了源，`npm install` 还是卡在 idealTree？

三个排查方向：1）有依赖走 git 直链或要从 GitHub 拉二进制（见上文），这类依赖不走镜像；2）旧 lockfile 里残留官方源地址，删除 node_modules 和 lockfile 后重试；3）用 npm config get proxy 确认没有残留的失效代理配置。

Docker 构建镜像时怎么用国内源？

在 Dockerfile 中显式设置即可：

RUN npm config set registry https://registry.npmmirror.com
RUN pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

顺带一提，Docker Hub 本身在国内拉取也很慢，解法参考《Docker Hub 拉取镜像慢？国内加速完整方案》。

用了 VPN 还需要换镜像源吗？

看线路质量。普通全局 VPN 走拥挤出口时，直连官方源未必比国内镜像快；JetStream 这类支持智能分流的方案下，国内镜像依然直连（保持最快），只有官方源和 GitHub 流量走 VPN，两者取各自最优，所以推荐镜像 + 智能分流同时保留。

结语

npm/pip 装包慢是网络链路问题，不是你的电脑问题。先花两分钟把 npmmirror 和清华 TUNA 镜像配上，日常开发立刻起飞；再用 JetStream 的智能分流兜住 npm publish、git 依赖、私有包这些镜像覆盖不到的死角，从此告别”装个包等一下午”。

相关阅读：