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

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

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

为什么要搭建私有 npm？

一开始我们团队内部的做法是，把一些工具库直接放在 GitHub/GitLab 上，用 npm install git+ssh://... 的方式来安装。

这种方式虽然能用，但有几个痛点：

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

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

技术选型

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

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

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

搭建过程

1. 安装 Verdaccio

Node.js 版本要求 v18+

bash 复制代码

npm install -g verdaccio

安装完成后，直接运行：

bash 复制代码

verdaccio

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

2. 用户登录与发布

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

bash 复制代码

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

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

bash 复制代码

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

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

bash 复制代码

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

发布后就可以看到了

3. 在项目中使用

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

bash 复制代码

registry=http://localhost:4873

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

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

bash 复制代码

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

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

bash 复制代码

npm install @my-scope/xxx

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

bash 复制代码

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

4. 维护与更新

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

bash 复制代码

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']。这可以避免将测试文件、源码等不必要的内容发布出去。

json 复制代码

{
  "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。

bash 复制代码

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

命令执行顺序

bash 复制代码

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 足够应付大部分团队需求；
使用作用域可以很好地区分私有包和公共包；
搭建完成后，内部工具的发布和复用体验大大提升。

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