在内网搭私有 npm 源并缓存公共包（Verdaccio）

团队内网要装 npm 包，直接指向公网源有两个麻烦：私有包不能公开，公网源一旦抖动，或者某个包被下架，构建就断。Verdaccio 把这两件事收进一个进程里解决。

Verdaccio 是一套用 TypeScript 写的轻量级私有 npm registry，自带小型数据库，能代理并缓存 npmjs.org 等上游源，让团队在内网发布、复用 npm 包。

它同时承担三种角色：私有包仓库、上游源的缓存代理、多个 registry 的聚合出口。启动不依赖外部数据库，代理下载过的模块留在本地，同一个版本再次安装时直接从缓存返回。项目采用 MIT 许可证，仓库地址是 https://github.com/verdaccio/verdaccio ，Star 17905，主要语言 TypeScript 占 94.5%。

装它需要什么

• Node.js：本仓库 master 分支与 next-9 发布线要求 v24 或更高；6.x 分支要求 Node.js 22 以上。
• 包管理器：npm、yarn、pnpm 任选一种，也可以走 Docker 镜像或 Helm chart。
• 端口：默认监听 4873，本机需要能占用这个端口。
• 数据库：不需要。Verdaccio 自带一个小型数据库，装上就能用。
• 存储扩展（可选）：要接 Amazon S3、Google Cloud Storage 这类服务，需要另外安装社区插件。

跑起来

1. 全局安装：npm install -g verdaccio@next-9；换 yarn 是 yarn global add verdaccio@next-9，换 pnpm 是 pnpm i -g verdaccio@next-9。
2. Docker 方式：docker pull verdaccio/verdaccio:nightly-master。
3. Helm 方式：helm repo add verdaccio https://charts.verdaccio.org，接着 helm repo update，再 helm install verdaccio/verdaccio。
4. 启动服务：在终端执行 verdaccio。
5. 可选地把 npm 指向它：npm set registry http://localhost:4873/；只对单次命令生效则用 NPM_CONFIG_REGISTRY=http://localhost:4873 npm i。

输出是什么

服务默认跑在 http://localhost:4873/ ，浏览器打开能看到本地包列表并支持搜索。包的元数据与缓存都落在 Verdaccio 自己的小型数据库和本地存储里，不需要额外配置。

判断这次跑成功很简单：终端里 verdaccio 进程没有报错退出，页面能打开，执行 npm publish 之后新包出现在列表中，代理过的公共包在公网不可用时仍能从缓存安装。

先说它做不到什么

它不支持 PM2 的 cluster 模式，README 里对这一点有明确标注，想靠多进程横向扩展行不通。

集群部署有过一段历史问题：早期的 Verdaccio 与 sinopia 在内部缓存了一份包列表，不重新解析 .sinopia-db，多节点同时跑时数据会不一致。这条 Issue 当前标记为已解决。

默认存储只有自带的本地小型数据库。想换成对象存储或其他后端，得自己安装社区插件，仓库里没有内置这些能力。

几个已经被修掉的坑也值得知道：大包下载会报 Unexpected EOF while installing/downloading large packages；scoped 包发布曾因斜杠转义失败；Windows Server 上出现过只留下 package.json、不保存 tarball；Docker 容器里 /config/ 目录映射到宿主机曾导致容器起不来。这些在后续版本中都处理掉了。

单机跑一个内网私有源、给 CI 做端到端测试、把多个上游 registry 收成一个出口，这些场景 Verdaccio 够用，README 里提到 create-react-app、pnpm、storybook 等项目都在这么做。需要多节点高可用、或者想要完全托管服务的团队，得先自己解决集群与存储插件这两块，它本身不提供。

焚评：这个项目的量化评分

本项目的选题来自 焚.com（一个按公开公式给 GitHub 项目打分的站）。焚评当前总分 10.0 分（满分 10）。下表是各维度的得分：

评分口径、权重与计算方式见焚.com 的评分方法页；数据随 GitHub 指标刷新，具体数值以焚.com 当前页面为准。本文正文为诀.com 独立撰写，评分数据由焚.com 授权引用。