15.3 私有 npm 仓库搭建：Verdaccio

在实际团队开发中，很多代码并不适合发布到公共 npm 仓库。企业内部的基础组件、业务工具库、甚至是未公开发布的私有包，都需要一个安全、可控的存储和分发渠道。搭建私有 npm 仓库就是为了解决这个问题，而 Verdaccio 是目前最主流、轻量且零配置的开源方案。

15.3.1 Verdaccio 是什么

Verdaccio 是一个用 Node.js 编写的轻量级私有 npm 仓库，它完全兼容 npm、yarn、pnpm 客户端，你可以像使用官方 npm registry 一样，向自己的私有仓库执行 publish 和 install。它的核心特点包括：

• 零配置启动：默认安装后一条命令就能运行一个可用的私有 registry。
• 代理与缓存：可以配置上游镜像（如淘宝镜像或官方 registry），当私有仓库中没有某个包时，自动从上游拉取并缓存，下次安装直接命中本地，节省带宽。
• 权限控制：支持用户注册、登录、包级别的发布/访问权限管理。
• 轻量：仅需 Node.js 环境，内存占用极低，适合部署在开发服务器上。
• 插件体系：可以扩展认证方式（如 LDAP、GitLab OAuth）、存储后端（如 AWS S3）、通知等。

很多中大型团队会在内部搭建一个 Verdaccio 实例，作为前端/Node.js 项目的统一包管理入口。这样做的好处是：既能沉淀组织内部的公共模块，又能加速安装，还能够管控包的发布权限，避免版本混乱。

15.3.2 安装与快速启动

Verdaccio 可通过 npm 全局安装：

npm install -g verdaccio

安装完成后，在终端直接运行 verdaccio 命令：

verdaccio

默认会监听 http://localhost:4873，并自动创建一个默认的配置文件。此时一个可用的私有仓库已经运行起来了。你可以打开浏览器访问 http://localhost:4873，会看到一个简洁的 Web 界面，显示当前已发布的包列表。

15.3.3 配置详解

Verdaccio 的配置文件默认位于 ~/.config/verdaccio/config.yaml（不同操作系统路径可能不同，首次运行时控制台会打印路径）。一个典型的生产配置大致如下：

# 存储包文件的目录
storage: ./storage

# 插件目录
plugins: ./plugins

# Web 界面配置
web:
  title: 我的私有仓库
  gravatar: true

# 认证配置
auth:
  htpasswd:
    file: ./htpasswd
    max_users: 1000  # 允许注册的最大用户数

# 上游代理配置（包的“代理链”）
uplinks:
  npmjs:
    url: https://registry.npmjs.org/
  taobao:
    url: https://registry.npmmirror.com/

# 包访问规则
packages:
  '@my-company/*':
    access: $authenticated   # 只有登录用户能访问
    publish: $authenticated   # 只有登录用户能发布
    unpublish: $authenticated

  '**':
    access: $all            # 所有用户（包括未登录）可安装
    publish: $authenticated
    unpublish: $authenticated
    proxy: taobao           # 如果包不存在，走淘宝镜像代理

# 服务器监听配置
server:
  keepAliveTimeout: 60

# 中间件
middlewares:
  audit:
    enabled: true

# 日志
logs:
  - { type: stdout, format: pretty, level: http }

关键字段说明：

• storage：存放包数据的本地目录，建议映射到持久化卷（Docker 环境）。
• uplinks：定义上游 registry，支持多个。可以通过 proxy 字段指定某个包或某组包走的上游。
• packages：包粒度的访问控制。access 表示谁能安装（$all 表示所有人，$authenticated 表示登录用户）；publish 表示谁能发布；unpublish 表示谁能取消发布。支持按 scope（@scope/*）分组设置。
• auth：默认使用 htpasswd 进行用户名密码认证，用户通过 npm adduser 注册，密码加密存于 htpasswd 文件。

启动时可以指定配置文件路径：

verdaccio --config /path/to/config.yaml

15.3.4 使用方式：发布与安装

注册用户与登录

在客户端，需要将 npm registry 指向 Verdaccio 服务地址：

npm set registry http://your-verdaccio-server:4873

或者更灵活地，可以使用 .npmrc 为特定 scope 指定 registry：

@my-company:registry=http://your-verdaccio-server:4873/

然后添加用户（相当于注册）：

npm adduser --registry http://your-verdaccio-server:4873

按照提示输入用户名、密码和邮箱，Verdaccio 会在 htpasswd 文件中创建用户记录。之后登录：

npm login --registry http://your-verdaccio-server:4873

发布包

在私有 npm 包的项目根目录下，确保 package.json 的 name 符合 registry 中配置的权限规则（例如 @my-company/my-lib），然后执行：

npm publish --registry http://your-verdaccio-server:4873

如果已经在 .npmrc 中设置了 scope 对应的 registry，可以直接 npm publish。

安装私有包

只需像安装普通包一样：

npm install @my-company/my-lib

Verdaccio 会检查包是否存在，若不存在且配置了 proxy，则向上游 registry 查询。上游返回结果后会缓存到本地 storage，后续安装直接走本地。

15.3.5 Docker 部署

Verdaccio 官方提供了 Docker 镜像，非常适合容器化环境。一个基础的 docker-compose.yml 示例：

version: '3'
services:
  verdaccio:
    image: verdaccio/verdaccio:5
    container_name: verdaccio
    ports:
      - "4873:4873"
    volumes:
      - "./storage:/verdaccio/storage"
      - "./config:/verdaccio/conf"
    environment:
      - VERDACCIO_PORT=4873

将自定义的 config.yaml 放入 ./config 目录，保证 storage 目录映射到宿主机即可。启动后，访问宿主机的 4873 端口就能使用私有仓库了。

15.3.6 权限管理与安全实践

Verdaccio 自带的 htpasswd 认证适合小型团队，但对于规模较大的组织，可能需要对接现有的用户体系。这时可以使用 Verdaccio 的认证插件，例如：

• verdaccio-gitlab：使用 GitLab OAuth 登录。
• verdaccio-ldap：对接企业 LDAP/AD。
• verdaccio-github-oauth：使用 GitHub 账号登录。

安装插件后，在 config.yaml 的 auth 部分配置相应的参数即可。

此外，为了区分公共包和私有包，可以：

• 为公共包设置 access: $all，这样即使未登录也能安装，方便 CI 环境。
• 对带有团队 scope 的包设置 access: $authenticated，甚至限定特定的用户或群组。
• 利用 unpublish: $authenticated 但限制部分管理员，防止错误操作撤销生产依赖。

15.3.7 CI/CD 集成

在自动化流水线中使用私有仓库，通常需要在构建环境配置认证信息。常见做法是：

1. 在项目根目录或 CI 环境变量中设置 .npmrc，内容为：

//your-verdaccio-server:4873/:_authToken="base64编码的token"

1. 通过 Verdaccio 获取 token：

• 先登录（npm login），Verdaccio 会返回一个 token。
• 或者通过 API 直接生成。

1. 设置环境变量 NPM_CONFIG_REGISTRY 或项目级 .npmrc 指定 registry，确保 npm install 能从私有仓库拉取私有包。

由于 Verdaccio 可以代理上游 registry，即使没有启用直接访问外网，流水线也能通过 Verdaccio 安装所有公有包，同时加速安装过程。

15.3.8 常见问题与排查

• 无法安装包，报 404：检查包名是否正确，以及 packages 中的 access 权限是否设置为 $authenticated，而当前未登录。
• 发布失败，报 403：检查 publish 权限，并确认已 npm login。另外，如果包名包含 scope，而该 scope 未在配置中授权，也会被拒绝。
• 代理不生效：确认 packages 中的对应规则设置了 proxy 字段，并且 uplinks 中的上游 URL 可正常访问。
• HTTPS 支持：Verdaccio 本身仅支持 HTTP，但可以通过 Nginx 反向代理启用 HTTPS。将 Nginx 配置为 SSL 终结，然后 proxy_pass 到 Verdaccio 的 HTTP 端口即可。
• 存储迁移：如果使用文件系统存储，直接打包 storage 目录即可。若想使用 S3 等对象存储，可以使用社区插件 verdaccio-s3-storage。

15.3.9 Verdaccio 在 Monorepo 中的角色

结合 15.1 节提到的 pnpm workspace，团队可以将公共工具库放置在 Monorepo 的 packages 目录下开发，通过 workspace 协议本地链接。当某个包需要独立版本或对外发布时，再通过 npm publish 推送到 Verdaccio，其他项目或团队就能像安装第三方包一样使用。这种“私有仓库 + Monorepo”的组合，形成了完整的内部包生命周期管理：

• 开发阶段：workspace 本地快速迭代。
• 测试与发布：CI 自动打版本号并 publish 到 Verdaccio。
• 消费阶段：其他项目通过 npm install 拉取确定的版本。

这样的流程既保留了 Monorepo 的开发效率，又提供了跨项目共享的正式发布渠道，是工程化能力成熟的标志之一。

总结来说，Verdaccio 提供了一种低成本、高度可控的私有 npm 仓库解决方案。无论是小团队的知识沉淀，还是大企业的内部包治理，它都能灵活适应，并且与 npm 生态完美兼容。搭建一个自己的私有仓库，是 Node.js 工程化过程中的重要一步，也是保证项目长期可维护性的基础设施。