从零搭建私有 npm 仓库Verdaccio

一次完整的实战记录：部署 Verdaccio

前言

在实际工作中，我们经常需要开发一些公共组件或工具函数，在多个项目间共享。如果每次都复制粘贴代码，维护起来会非常痛苦。这时，搭建一个私有 npm 仓库就显得尤为重要。

本文记录了我从零开始搭建私有 npm 仓库、开发 Vue3 组件库并发布的全过程，包括遇到的坑和解决方案。希望能帮助到同样需要搭建私有仓库的开发者。

一、环境准备

1.1 硬件要求

一台云服务器（本文使用阿里云 ECS，CentOS 系统）
本地开发环境（Windows/Mac/Linux）

1.2 软件要求

Node.js 18+
pnpm 8+（推荐使用 pnpm 管理 Monorepo）
Docker（用于部署 Verdaccio）

二、部署 Verdaccio 私有仓库

2.1 阿里云安全组设置

在开始之前，需要确保你的阿里云服务器允许外部访问 4873 端口。

登录阿里云控制台，找到你的ECS实例。
进入"安全组" -> "配置规则"。
添加入方向规则：
- 端口范围 ：4873/4873
- 授权对象 ：0.0.0.0/0（如果需要更安全，可以限制为你的办公IP）
- 协议：TCP

2.2 安装 Docker

整个过程不详细说明，自己去看网络上的教程

2.3 拉取 Verdaccio 镜像

复制代码

sudo docker pull verdaccio/verdaccio

2.4 创建数据挂载目录

为了让你的npm包和配置在容器更新或重启后不丢失，我们需要在服务器上创建专门的目录。

点击宝塔面板左侧的文件。
进入你希望的目录，例如 /www/，然后新建一个文件夹，命名为 verdaccio。
进入 /www/verdaccio/ 目录，再新建两个子文件夹：conf 和 storage。
进入 conf 文件夹，新建一个文件，命名为 config.yaml。

编辑刚才新建的 /www/verdaccio/conf/config.yaml 文件，将以下内容复制进去并保存。

这个配置设置了存储路径、用户认证、上游源（淘宝镜像）和访问权限

bash 复制代码

# 包存储路径，对应我们挂载的storage目录
storage: /verdaccio/storage

# 用户认证，用户信息会保存在htpasswd文件中
auth:
  htpasswd:
    file: /verdaccio/conf/htpasswd

# 公共包去哪里下载（使用淘宝镜像加速）
uplinks:
  npmjs:
    url: https://registry.npmmirror.com/

# 包访问权限配置
packages:
  '@*/*':
    access: $all
    publish: $authenticated
    proxy: npmjs
  '**':
    access: $all
    publish: $authenticated
    proxy: npmjs

# 启动后的Web界面
web:
  title: locfly私有npm仓库
  enable: true

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

# 监听所有地址，允许外部访问
listen: 0.0.0.0:4873

2.5. 创建并运行容器

回到宝塔面板的 Docker 页面，点击本地镜像，选择 -> 创建容器。
按以下信息进行配置：
- 镜像：选择我们刚刚拉取的 verdaccio/verdaccio。
- 容器名 ：填写 verdaccio（随便填自己的）。
- 端口映射：
  - 容器端口：4873
  - 服务器端口：4873（确保与阿里云安全组开放的端口一致）
- 目录挂载：这是关键步骤，将服务器的目录映射到容器内部。下面的服务器目录是刚才创建的挂载目录，根据自己情况选择，容器目录不能改（其实这里跟前两天配置jenkins是一样的）
  - 服务器目录 ：/www/verdaccio/conf ------ 容器目录 ：/verdaccio/conf
  - 服务器目录 ：/www/verdaccio/storage ------ 容器目录 ：/verdaccio/storage
  - 注意：如果挂载时提示权限错误，进入到目录verdaccio，右键权限，把读写权限打开

2.6. 验证部署

现在，打开你的浏览器，访问 http://你的服务器公网IP:4873。如果能看到 Verdaccio 的页面，就说明部署成功啦！

三、常见问题与解决方案

问题1：添加用户时 500 错误

bash 复制代码

npm error code E500
npm error 500 Internal Server Error

原因： 目录权限问题，Verdaccio 容器没有写入权限。

解决方案：找到Verdaccio右键，然后选择权限，把读写权限打开或者自己找相关的命令去开权限