npm registry 国内镜像源完全指南 2026

npm install 卡在 sill idealTree、报 ETIMEDOUT 是国内前端日常。换镜像源是第一道也是最有效的优化。本文给 2026 仍在维护的镜像列表 + npm/pnpm/yarn/Bun 全套配置。

一、2026 仍可用的镜像源

镜像域名维护方稳定性
npmmirror(原淘宝)https://registry.npmmirror.com阿里 / 社区★★★★★
腾讯云https://mirrors.cloud.tencent.com/npm/腾讯★★★★
华为云https://mirrors.huaweicloud.com/repository/npm/华为★★★★
cnpmjshttps://r.cnpmjs.org/社区★★★(已不推主用)
字节https://bnpm.byted.org/字节内部(对外不开放)-

主推:npmmirror。同步频率高(~10 分钟)、稳定性最好、@types/* 等大量 scope 包都全。

二、npm 配置

临时(单次 install)

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

永久(写入 ~/.npmrc)

npm config set registry https://registry.npmmirror.com
# 验证
npm config get registry

多镜像备份(.npmrc)

registry=https://registry.npmmirror.com
# 备用:腾讯
# registry=https://mirrors.cloud.tencent.com/npm/

三、Yarn(v1 / Berry)配置

Yarn v1

yarn config set registry https://registry.npmmirror.com

Yarn Berry(v2/v3/v4)

yarn config set npmRegistryServer https://registry.npmmirror.com

或写 .yarnrc.yml:

npmRegistryServer: "https://registry.npmmirror.com"

四、pnpm 配置

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

或在 ~/.npmrc(pnpm 共用):

registry=https://registry.npmmirror.com

如果换镜像后 pnpm 还从旧镜像下:

pnpm store prune
rm -rf node_modules pnpm-lock.yaml
pnpm install

五、Bun 配置

Bun 1.0+ 读 ~/.npmrc:

registry=https://registry.npmmirror.com

或 bunfig.toml(更细粒度):

[install]
registry = "https://registry.npmmirror.com"

[install.scopes]
"@mycompany" = { url = "https://private.example.com/", token = "..." }

清理 cache:

bun pm cache rm

六、@scope 包混合配置

私有包走自己 registry,公开包走镜像:

# ~/.npmrc
registry=https://registry.npmmirror.com
@mycompany:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=ghp_xxxxx
@types:registry=https://registry.npmmirror.com

七、CI / Docker 环境配置

CI 配置在 .npmrc 文件提交到仓库:

registry=https://registry.npmmirror.com
network-timeout=600000
fetch-retries=5

Docker 镜像构建:

FROM node:20-alpine
RUN npm config set registry https://registry.npmmirror.com
COPY package*.json ./
RUN npm ci --prefer-offline

GitHub Actions 在国内 runner 上跑:

- name: Setup Node
  uses: actions/setup-node@v4
  with:
    node-version: 20
    registry-url: https://registry.npmmirror.com
- run: npm ci

八、企业内网方案

完全不通外网的环境:

Verdaccio(轻量级,推荐)

npm install -g verdaccio
verdaccio

默认 http://localhost:4873,有 GUI,可配上游 proxy。容器化:

docker run -d -p 4873:4873 verdaccio/verdaccio

Sonatype Nexus(企业级)

统一管理 npm / Maven / PyPI / Docker 等多种制品。重型,适合 1000+ 开发者团队。

JFrog Artifactory

商业方案,功能最全。

九、常见报错排查

报错原因解决
ETIMEDOUT / ENOTFOUNDDNS / 网络换镜像或检查代理
404 Not Found镜像未同步该包等 30 分钟或临时换官方
EAUTHtoken 失效重新 npm login
SSL/TLS error系统时间错 / 证书问题校准时间,清 ca
Sha512 mismatch镜像缓存损坏加 —force 或 pnpm store prune

十、镜像源 vs 走稳定代理

镜像源对 99% 场景够用。但有三种情况镜像不行:

  1. 新发布版本 install 后立刻拉 — 镜像有 10-30 分钟同步延迟
  2. 私有 npm 包(自家 registry 在境外) — 镜像不代理
  3. CI/CD 频繁拉镜像未命中的私有包 — 镜像 + 代理叠加

这些场景下,挂一条配套订阅线路把 registry.npmjs.org 走代理,与镜像源同时配置(.npmrc 走镜像 + 代理走 npm 官方),双保险。

十一、Yarn / pnpm / npm 跨工具同步配置

最简单:全部读 ~/.npmrc 的 registry= 一行,三个工具共用。

避免冲突:不要同时在 ~/.npmrc 和 .yarnrc.yml / bunfig.toml 写不同 registry。统一 ~/.npmrc 即可。

来源与时间戳

最后核对时间:2026-05-20。镜像源稳定性和同步频率可能动态变化。