ZhenYu's 知识库

外观

搭建私有 Npm 仓库

约 1030 字大约 3 分钟

2026-04-16

私有 Npm 的必要性

在团队开发中，搭建私有 Npm 仓库有以下几个重要原因：

内网包共享

  • 团队内部封装的公共组件、工具库需要在多个项目间共享
  • 避免重复造轮子，提高开发效率
  • 统一版本管理，确保各项目使用的依赖版本一致

加速访问

  • 内网部署的私有仓库访问速度远快于公网
  • 减少因网络问题导致的安装失败
  • 本地缓存机制，重复下载无需请求外网

包安全管理

  • 防止内部代码泄露到公网
  • 对第三方包进行安全审核
  • 控制生产环境的依赖来源

常见方案对比

方案特点适用场景推荐指数
Verdaccio轻量、易用、配置简单个人/小型团队
Nexus Repository Manager功能强大、可管理多种仓库类型中大型企业
CNPM国内使用广泛、兼容性好需要公网访问的场景
私有 npmjs.org官方方案、完整功能大型企业、有运维能力

Verdaccio（推荐）

  • 基于 Node.js 的轻量级私有仓库
  • 开源免费，无需付费
  • 配置简单，上手快
  • 支持 Docker 部署
  • 默认支持用户认证

Nexus Repository Manager

  • Sonatype 出品的企业级仓库管理器
  • 支持 npm、Maven、Docker 等多种仓库类型
  • 权限管理精细，适合大型团队
  • 资源占用相对较高

CNPM

  • 阿里巴巴开源的私有仓库方案
  • 兼容公网 npmjs.org
  • 支持同步公网包到内网
  • 国内使用广泛，社区活跃

Verdaccio 部署

Docker 部署

# 最基础的运行方式
docker run -d \
  --name verdaccio \
  -p 4873:4873 \
  verdaccio/verdaccio

Docker Compose 配置

# docker-compose.yml
version: '3.8'

services:
  verdaccio:
    image: verdaccio/verdaccio:5
    container_name: verdaccio
    ports:
      - "4873:4873"
    volumes:
      - ./data:/verdaccio/conf
      - ./storage:/verdaccio/storage
    environment:
      - VERDACCIO_PROTOCOL=https
      - VERDACCIO_PORT=4873

认证与权限管理

Verdaccio 默认使用基于文件的用户配置，主要配置文件为 htpasswd：

# conf/htpasswd.yaml
# 用户名:$2y$xxxxxxxxxx:email
# 格式：bcrypt 加密的密码
zhenyu:
  hash: $2y$10$xxxxxxxxxx
  email: zhenyu@example.com
  groups: []
admin:
  hash: $2y$10$yyyyyyyyyy
  email: admin@example.com
  groups:
    - admin

添加新用户：

# 使用 htpasswd 工具生成密码
htpasswd -nbB username password >> conf/htpasswd.yaml

使用配置

.npmrc 配置

在项目根目录创建 .npmrc 文件：

# 私有仓库地址
@scope:registry=http://localhost:4873

# 认证信息（可选，推荐使用 token）
# //localhost:4873/:_authToken=NpmToken.xxxxxx

scope 作用域

使用 scope 可以区分私有包和公共包：

# .npmrc
@mycompany:registry=http://localhost:4873

使用私有包：

// 安装私有包
npm install @mycompany/utils

// 或者在 package.json 中
{
  "dependencies": {
    "@mycompany/utils": "^1.0.0"
  }
}

发布包

登录到私有仓库：

npm adduser --registry=http://localhost:4873
# 输入用户名、密码、邮箱

# 或者使用 token 登录
npm config set //localhost:4873/:_authToken=NpmToken.xxxxxx

发布包：

# 发布到私有仓库
npm publish --registry=http://localhost:4873

# 带 scope 的包发布
npm publish --access restricted --registry=http://localhost:4873

前端 Monorepo 中的使用（pnpm workspace）

在 monorepo 项目中，私有仓库常用于共享包的发布和管理。

pnpm workspace 配置

# pnpm-workspace.yaml
packages:
  - 'packages/*'
  - 'apps/*'

在 package.json 中引用私有包

{
  "name": "@mycompany/app-web",
  "dependencies": {
    "@mycompany/ui": "workspace:*",
    "@mycompany/utils": "workspace:*"
  }
}

发布私有包

使用 pnpm publish 配合私有仓库：

# 在 packages/utils 目录下
cd packages/utils
npm publish --registry=http://localhost:4873

或者在 package.json 中配置 publishConfig：

{
  "name": "@mycompany/utils",
  "publishConfig": {
    "registry": "http://localhost:4873",
    "access": "restricted"
  }
}

最佳实践建议

仓库规划

  • 按团队或项目划分作用域（scope）
  • 统一命名规范，如 @公司名/包名
  • 合理规划仓库数量，避免过度分散

权限管理

  • 生产环境使用 HTTPS 和强密码策略
  • 定期轮换访问令牌
  • 按角色分配不同权限（发布者、消费者）

包管理

  • 使用语义化版本号（SemVer）
  • 合理设置版本范围，避免隐性升级
  • 建立包的文档和使用规范

运维建议

  • 定期备份存储数据
  • 配置监控和告警
  • 做好容量规划
  • 记录日志便于排查问题

安全建议

  • 私有仓库不对公网暴露
  • 定期更新 Verdaccio 版本
  • 审核第三方依赖的安全性
  • 限制内部包的发布权限