NPM私有仓库配置

为什么需要NPM私有仓库

企业内部开发时，经常需要共享一些私有模块。这些模块可能包含敏感代码或业务逻辑，不适合发布到公共NPM仓库。搭建私有NPM仓库可以解决以下问题：

• 安全地存储和分发私有包
• 控制包的访问权限
• 加速依赖安装（通过缓存公共包）
• 统一管理内部依赖版本

常见NPM私有仓库解决方案

Verdaccio

Verdaccio是一个轻量级的私有NPM代理注册表，具有以下特点：

• 零配置即可运行
• 支持插件系统
• 内置小型数据库
• 支持Docker部署

安装Verdaccio：

npm install -g verdaccio

启动服务：

verdaccio

Nexus Repository

Nexus是一个功能更强大的仓库管理器，支持多种包格式：

• 支持NPM、Maven、Docker等多种仓库类型
• 提供细粒度的权限控制
• 支持高可用部署

GitHub Packages

GitHub提供的包管理服务：

• 与GitHub仓库深度集成
• 支持NPM、Maven、RubyGems等
• 免费套餐有一定限制

Verdaccio详细配置

基本配置

Verdaccio的配置文件通常位于~/.config/verdaccio/config.yaml，主要配置项：

storage: ./storage
plugins: ./plugins

web:
  title: Verdaccio
  # comment out to disable gravatar support
  # gravatar: false

auth:
  htpasswd:
    file: ./htpasswd
    # Maximum amount of users allowed to register, defaults to "+inf".
    # You can set this to -1 to disable registration.
    # max_users: 1000

uplinks:
  npmjs:
    url: https://registry.npmjs.org/

packages:
  '@*/*':
    access: $all
    publish: $authenticated
    proxy: npmjs

  '**':
    access: $all
    publish: $authenticated
    proxy: npmjs

server:
  keepAliveTimeout: 60

middlewares:
  audit:
    enabled: true

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

用户认证

添加用户：

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

登录：

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

发布包

在项目目录中：

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

客户端配置

全局使用私有仓库

设置npm默认registry：

npm config set registry http://localhost:4873

项目级配置

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

registry=http://localhost:4873
//localhost:4873/:_authToken="your-auth-token"

作用域包(Scoped Packages)

对于特定作用域的包，可以单独配置registry：

npm config set @mycompany:registry http://localhost:4873

或者在package.json中：

{
  "publishConfig": {
    "registry": "http://localhost:4873"
  }
}

高级配置

插件系统

安装插件示例（如verdaccio-auth-memory）：

npm install verdaccio-auth-memory

然后在配置文件中启用：

auth:
  auth-memory:
    users:
      admin:
        password: $2a$10$... # bcrypt加密的密码

HTTPS配置

生成自签名证书：

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

配置HTTPS：

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

集群部署

使用PM2运行多个实例：

pm2 start verdaccio --name="verdaccio" -i max

配置共享存储：

storage: /shared/storage

与CI/CD集成

GitHub Actions示例

name: Publish Package

on:
  push:
    branches: [ main ]

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v2
        with:
          node-version: '14'
      - run: npm install
      - run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

私有依赖安装

在CI中安装私有依赖：

echo "//registry.npmjs.org/:_authToken=$NPM_TOKEN" > .npmrc
npm install

性能优化

缓存策略

配置上游代理缓存：

uplinks:
  npmjs:
    url: https://registry.npmjs.org/
    cache: true
    maxage: 30m
    max_fails: 3

存储优化

使用外部存储：

store:
  memory:
    limit: 1000

监控与维护

日志分析

配置日志级别：

logs:
  - {type: file, path: verdaccio.log, level: info}
  - {type: stdout, format: pretty, level: http}

健康检查

添加健康检查端点：

server:
  healthCheck:
    enabled: true
    interval: 30

迁移现有包

从公共仓库迁移

下载并重新发布：

npm pack some-package
tar -xzvf some-package-1.0.0.tgz
cd package
npm publish --registry http://localhost:4873

批量迁移工具

使用npm-download和npm-upload工具：

npm install -g npm-download npm-upload
npm-download --registry https://registry.npmjs.org some-package
npm-upload --registry http://localhost:4873 some-package-1.0.0.tgz

常见问题解决

权限问题

错误示例：

npm ERR! code E403
npm ERR! 403 403 Forbidden - PUT http://localhost:4873/my-package

解决方案：

1. 确保已登录
2. 检查包名是否已被占用
3. 验证用户是否有发布权限

代理问题

配置代理：

http_proxy: http://proxy.example.com:8080
https_proxy: http://proxy.example.com:8080
no_proxy: localhost,127.0.0.1

存储空间不足

清理旧版本：

verdaccio-storage cleanup --config ~/.config/verdaccio/config.yaml

或配置自动清理：

store:
  cleanup:
    enabled: true
    max_versions: 5
    max_days: 30