npm registry 国内镜像源完全指南 2026-乒乓球世界杯日本-2022世界杯分组_世界杯南美区几个名额

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 loginSSL/TLS error系统时间错 / 证书问题校准时间,清 caSha512 mismatch镜像缓存损坏加 —force 或 pnpm store prune

十、镜像源 vs 走稳定代理

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

新发布版本 install 后立刻拉 — 镜像有 10-30 分钟同步延迟

私有 npm 包(自家 registry 在境外) — 镜像不代理

CI/CD 频繁拉镜像未命中的私有包 — 镜像 + 代理叠加

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

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

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

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