搭建私有 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/verdaccioDocker 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.xxxxxxscope 作用域
使用 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 版本
- 审核第三方依赖的安全性
- 限制内部包的发布权限
