【本地搭建npm私服】使用Verdaccio

使用Verdaccio搭建本地NPM私服及私有包管理指南

一、Verdaccio安装与基础配置

1. 安装Verdaccio

# 全局安装Verdaccio
npm install -g verdaccio

# 检查版本
verdaccio --version

2. 启动服务

verdaccio

启动后默认监听4873端口，访问 http://localhost:4873

3. 配置npm客户端

# 设置npm使用本地仓库
npm set registry http://localhost:4873/

# 恢复官方源(需要时使用)
npm set registry https://registry.npmjs.org/

二、配置文件详解

配置文件路径：~/.config/verdaccio/config.yaml

核心配置项：

# 存储目录
storage: ./storage

# 认证配置
auth:
  htpasswd:
    file: ./htpasswd
    max_users: 1000  # -1禁止注册，1000允许1000用户

# 上游链接
uplinks:
  npmjs:
    url: https://registry.npmjs.org/

# 包访问控制
packages:
  '@scope/*':  # 作用域包
    access: $authenticated  # 访问权限
    publish: $authenticated # 发布权限
    proxy: npmjs  # 代理设置
    
  '**':  # 所有包
    access: $all
    publish: $authenticated
    proxy: npmjs

# 服务器配置
listen:
  - 0.0.0.0:4873  # 监听所有网络接口

三、用户管理

1. 创建用户

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

按提示输入用户名、密码和邮箱

2. 登录用户

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

3. 查看当前用户

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

四、私有包管理

1. 发布私有包

# 在项目目录中
npm publish --registry http://localhost:4873

对于作用域包(@scope/package)，需要：

npm publish --access=public --registry http://localhost:4873

2. 更新私有包

修改package.json中的version后：

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

3. 安装私有包

npm install @scope/package --registry http://localhost:4873

4. 删除私有包

npm unpublish @scope/package --force --registry http://localhost:4873

五、高级管理功能

1. 设置包访问权限

修改config.yaml：

packages:
  '@private/*':
    access: $authenticated  # 仅认证用户可访问
    publish: admin group  # 仅admin组可发布

2. 使用插件扩展功能

安装存储插件示例：

npm install verdaccio-aws-s3-storage

配置插件：

store:
  aws-s3-storage:
    bucket: your-bucket-name
    region: us-east-1

3. 配置HTTPS

生成证书：

openssl req -x509 -newkey rsa:2048 -nodes -keyout key.pem -out cert.pem -days 365

配置HTTPS：

https:
  key: /path/to/key.pem
  cert: /path/to/cert.pem

六、日常维护

1. 备份数据

# 备份storage目录
tar -czvf verdaccio-backup.tar.gz ~/.config/verdaccio/storage

2. 清理旧版本

安装清理插件：

npm install verdaccio-clean-storage

配置自动清理：

plugins:
  clean-storage:
    keep: 5  # 保留最近5个版本
    interval: 86400  # 每天清理一次(秒)

3. 性能监控

# 查看存储使用情况
du -sh ~/.config/verdaccio/storage

七、常见问题解决

1. 发布失败：403 Forbidden

   • 检查用户是否已登录
   • 检查package.json中的name是否与已有包冲突

2. 安装超时

   • 检查uplinks配置是否正确
   • 临时关闭代理：npm config rm proxy

3. 存储空间不足

   • 清理旧版本：npm cache clean --force
   • 扩展storage目录或使用外部存储插件

4. 插件不生效

   • 确保插件已安装在Verdaccio同目录下
   • 检查插件名称与配置一致

通过以上配置，你可以建立一个功能完善的本地NPM私有仓库，满足团队私有包管理需求。根据团队规模，可以进一步配置集群部署和负载均衡。