【实录】应用 Verdaccio 从零搭建私有 npm 仓库（含完整步骤及避坑指南）

在日常开发中，我们经常需要使用 npm 包来加速项目的开发。但有些时候，公司内部会有一些私有组件、工具库不适合直接发布到 npm 公共仓库，这时就需要一个 私有 npm 仓库 来托管。

最近我就亲手搭建了一次，过程踩了一些坑，这里记录下来，或许能帮到有类似需求的你。

---

为什么要搭建私有 npm？

一开始我们团队内部的做法是，把一些工具库直接放在 GitHub/GitLab 上，用 npm install git+ssh://... 的方式来安装。
这种方式虽然能用，但有几个痛点：

• 每次安装都要拉整个仓库，速度很慢；
• 版本管理不够清晰，容易混乱；
• 无法复用 npm 上的缓存机制。

于是我决定搞一个 私有 npm 服务，既能像用官方 npm 那样方便 install，又能保证内部代码的安全。

---

技术选型

我调研了一下，常见的方案有两个：

1. Verdaccio：一个轻量级的私有 npm 服务器，用 Node.js 写的，部署简单，功能也够用。
2. cnpmjs.org：由阿里开源的企业级 npm 服务器，更重一些，但功能强大。

最后我选择了 Verdaccio，因为我们团队的需求比较轻量，不需要太复杂的功能。

---

搭建过程

1. 安装 Verdaccio

Node.js 版本要求 v18+

npm install -g verdaccio

安装完成后，直接运行：

verdaccio

默认会在本地的 http://localhost:4873 启动服务，浏览器直接访问即可:

---

2. 用户登录与发布

首次初始化需先创建用户：

npm adduser --registry http://localhost:4873

后面再次登录可使用命令:

npm login --registry=http://localhost:4873

输入用户名、密码、邮箱之后，就可以发布了：

npm publish --registry http://localhost:4873

发布后就可以看到了

---

3. 在项目中使用

为了让 npm 安装包时能访问到我这个私有仓库，需要修改 .npmrc 文件：

registry=http://localhost:4873

这样，所有 npm install 命令都会走我自己的仓库了。

如果只是想 部分包走私有源，可以用作用域的方式，比如：

@my-scope:registry=http://localhost:4873

在项目里，只要 .npmrc 配置正确，就能直接安装：

npm install @my-scope/xxx

如果指向临时指定一下仓库可以:

npm install @my-scope/xxx --registry=http://localhost:4873

4. 维护与更新

更新版本号: 在发布新版本前，需要更新 package.json 中的 version 字段，可以执行 npm version xxx 命令:

npm version patch # 修复bug，小改动 (1.0.0 -> 1.0.1)
npm version minor # 新增功能，向后兼容 (1.0.1 -> 1.1.0)
npm version major # 重大变更，不兼容 (1.1.0 -> 2.0.0)

命令会自动修改 package.json 中的 version 并创建一个 git commit 和 tag。

再次执行 publish 命令即可。

---

注意事项

package.json 关键项检查

• private: 需设置为 false。

• publishConfig: 指定发布到的仓库地址，这样就不用每次执行 publish 命令时后面追加仓库地址了。

• name: 包名，命名规范（比如要求统一的 scope，如 @mycompany/）。

• version: 版本号，遵循语义化版本控制 (SemVer)，即 主版本号.次版本号.修订号。每次发布新版本时都需要更新。

• main: 入口文件。指向你 SDK 打包后的主要文件（例如 dist/index.js 或 lib/index.js）。

• files: （可选）一个数组，指定哪些文件和目录需要被发布到 npm。例如 [‘dist/’, ‘lib/’, ‘README.md’]。这可以避免将测试文件、源码等不必要的内容发布出去。

{
"name": "@mycompany/xxxx",
"private": false,
"version": "1.0.12",
"main": "dist/xxxxx.umd.js",
"files": [
"dist"
],
"publishConfig": {
"registry": "http://your-company-npm-registry.com:4873/"
}
}

使用 nrm 管理多个 registry

如果经常需要在官方源和多个私有源之间切换，可以使用 nrm 工具来管理和切换，切换后使用 npm 命令时就会默认指向你设置的 registry。

# 安装 nrm
npm install -g nrm
# 添加私有源
nrm add mycompany http://your-company-registry-url
# 切换到私有源
nrm use mycompany # 切换回官方源: nrm use npm

命令执行顺序

git add .
git commit -m "fix: 修复 xxx 问题"
# 版本号 + 自动生成 commit 和 tag
npm version patch # 或 npm version minor / major
# 把代码和 tag 一起推送
git push origin main --tags
# 构建产物
npm run build
# 发布到 npm
npm publish

---

总结

通过这次实践，我学会了：

• 搭建私有 npm 仓库其实很简单，Verdaccio 足够应付大部分团队需求；
• 使用作用域可以很好地区分私有包和公共包；
• 搭建完成后，内部工具的发布和复用体验大大提升。

如果你也有类似需求，不妨试试自己搭一个，过程比想象的轻松。