有些时候我们可能会有创建私有 npm 仓库的需求，例如公司内部使用、个人创建 npm 包测试发布上传，甚至或许仅仅只是自己想的绝妙名字在公共 npm 仓库上已被占用。这种时候可以尝试使用 verdaccio 来搭建一个 npm 私有服务器。

介绍

Verdaccio 是一个由 Node.js 构建的轻量级私有 npm 代理注册源。详细信息可参考他的官方文档 Verdaccio

使用 Verdaccio 有诸多优势：

1. 搭建简单，开箱即用
2. 丰富的配置项满足个人定制需求
3. 应用搭建在局域网内，允许个人或公开使用
4. 可以对 npm 包的访问、发布、撤回配置权限管理
5. 对下载过的依赖包进行缓存，以加快再次下载速度
6. 与 yarn、npm 和 pnpm 100% 兼容

安装及运行

普通窗口模式

Verdaccio 的安装非常简单，两步即可启动

1
2
3

npm i --location=global verdaccio
# 启动服务器
verdaccio

启动后可以得到如下运行结果：

1
2
3
4

info --- config file  - C:\Users\DELL\AppData\Roaming\verdaccio\config.yaml
info --- plugin successfully loaded: verdaccio-htpasswd
info --- plugin successfully loaded: verdaccio-audit
warn --- http address - http://localhost:4873/ - verdaccio/5.23.2

运行结果中展示了两条信息：

1. 配置文件位于 C:\Users\DELL\AppData\Roaming\verdaccio\config.yaml，我们之后需要修改该文件来进行自定义配置
2. 服务在端口 4873 上启动，此时已经可以通过 http://localhost:4873/ 查看管理界面了

此时若关闭或 ctrl + C 结束进程，服务也会被一并关闭。可以考虑通过 pm2 等工具来实现后台持久运行。这里不做赘述。

Docker

处于便于管理与数据迁移，在服务器上个人更喜欢使用 Docker 部署。本文参考官方文档 Running Verdaccio using Docker

首先创建相关目录文件：

1
2
3
4

# 创建根目录
mkdir /opt/verdaccio && cd /opt/verdaccio
# 创建相关数据存放目录
mkdir plugins storage storage/data

创建一个用完就丢的容器来获取配置文件 config.yml：

1
2
3
4
5
6

# 创建容器
docker run -it --rm --name verdaccio verdaccio/verdaccio:latest
# 提取配置文件至当前目录下的 conf 目录下
docker cp verdaccio:/verdaccio/conf/config.yaml ./conf/config.yaml
# 删除容器
docker rm -f verdaccio

创建 docker-compose.yml 文件，向其中填写如下内容

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

version: "3.7"
services:
  verdaccio:
    image: verdaccio/verdaccio:latest
    container_name: verdaccio
    ports:
      - "4873:4873"
    networks:
      - node-network
    environment:
      - TZ=Asia/Shanghai
      - VERDACCIO_PORT=4873
    restart: always
    volumes:
      - ./conf:/verdaccio/conf
      - ./storage:/verdaccio/storage
      - ./plugins:/verdaccio/plugins
networks:
  node-network:
    driver: bridge

由于 Verdaccio 在容器内以非 root 用户 (uid=10001) 运行，设置了 volumes 挂载覆盖掉默认值后，涉及到到写入文件时会存在权限错误导致操作失败，此时需要确保挂载目录分配给正确的用户。

1
2

# 将整个目录对 10001 用户开放
sudo chown -R 10001:65533 .

启动容器即可在 服务器ip:4873 看到管理后台网页了。

1

docker-compose up -d

使用 Verdaccio

服务开启后，我们需要将当前的 npm 源切换为我们的私人 npm 服务器地址。这里可以使用 nrm 来实现。

1
2
3
4
5
6

# 全局 安装 nrm
npm i --location=global nrm
# 新增 npm 源
nrm add myNpm http://localhost:4873/
# 切换 npm 源
nrm use myNpm

注册并登录 npm 账号，将会依次提示输入 username、password、email。

1

npm adduser

然后就可以进行 npm 的相关操作了。补充其他操作方法：

1
2
3
4
5
6

# 登录用户
npm login
# 登出用户
npm logout
# 发布 npm 包
npm publish

配置文件

Verdaccio 提供了丰富的配置项供我们定制化修改。建议配合官方文档食用 Configuration File。

提问：还记得配置文件在哪里吗？（笑

1. 普通窗口化使用时配置文件位于启动时打印的日志信息中
2. Docker 启动时则位于我们提取至的 根目录/conf 目录下

这里对部分较难理解配置项做出解释

listen

Verdaccio 默认只能本机访问，我们可以配置 0.0.0.0:端口，公开让其他人访问。

1
2

listen:
  - 0.0.0.0:4873

uplinks

在安装 npm 包时，Verdaccio 会先尝试在本地查找，若找不到则会前往上游链接（uplinks）查找。

uplink 用于配置上游链接的别名和地址，允许配置多个：

1
2
3
4
5
6
7

uplinks:
  npm:
    url: https://registry.npmjs.org/
  yarn:
    url: https://registry.yarnpkg.com/
  taobao:
    url: https://registry.npmmirror.com/

auth

auth 配置项常用配置结构如下

1
2
3
4
5

auth:
  htpasswd:
    file: /verdaccio/storage/htpasswd
    max_users: 1
    algorithm: bcrypt

verdaccio 默认使用 htpasswd 插件进行身份存储校验，这里为针对 htpasswd 的配置项

• file: 用户数据存储文件位置
• max_users: 最多注册用户数量，可设置为 -1 禁止注册
• algorithm: 校验算法。verdaccio 的默认校验算法是 crypt，这被认定是不安全的，在 v6 bcrypt 算法被默认支持之前，建议手动设置配置项使用 bcrypt 校验。

用户权限相关解释

verdaccio 内置了下面几种权限：

• $all: 全部用户
• $anonymous: 匿名用户
• $authenticated: 登录用户

而 verdaccio 默认使用的 htpasswd 插件不实现 allow_access、allow_publish 和 allow_unpublish 方法。因此其对于上面三种权限用以下方式处理：

• 当你没有登录时，$all 和 $anonymous 意义相同，均对你有效
• 当你登陆后，$all 与 $authenticated 对你有效，$anonymous 被排除在外

packages

这里为包访问相关配置，具体配置项参考官网 Package Access。这里仅做部分解释

该配置项结构如下：

1
2
3
4
5
6
7
8
9
10
11
12
13

packages:
  # scoped packages
  '@scope/*':
    access: $all
    publish: $anonymous
    unpublish: $authenticated
    proxy: taobao

  'private-*':
    access: $all
    publish: $anonymous
    unpublish: $authenticated
    proxy: taobao

其中键名的含义为：匹配包名称以 @scope/ / private- 开头的 npm 包，当键名为 "**" 时，匹配所有 npm 包。

而 proxy 参数则指向了上面 uplinks 配置项配置的上游链接别名。

结合上文 auth 相关内容，这里的配置项解释为：包名称以 @scope/ / private- 开头的 npm 包，所有用户均能查看（access），仅匿名用户可以发布（publish），仅登录用户可以撤回（unpublish），当在本地找到对应 npm 包时，前往别名为 taobao 的上游链接查找下载。