Verdaccio离线publish为什么会报错？

在构建和维护企业内部开发环境时，使用 Verdaccio 搭建一个私有的 npm 包代理仓库是一种常见且高效的实践，它不仅能加速依赖包的下载、实现流量缓存，还能作为企业内部私有包的发布和管理中心，在完全隔离的内网或离线环境中，开发者常常会遇到一个棘手的问题：尝试向离线的 Verdaccio 服务器发布包时，控制台会抛出网络连接相关的错误，导致发布失败，本文将深入探讨此问题的根源，并提供一套清晰、可操作的解决方案。

问题现象与错误分析

当您在内网环境中执行 npm publish 命令，目标是离线的 Verdaccio 服务器时，最常见的报错信息通常指向无法连接到外部的 npm 官方源,错误信息可能类似于：

npm ERR! code ECONNREFUSED
npm ERR! errno ECONNREFUSED
npm ERR! request to https://registry.npmjs.org/xxx failed, reason: connect ECONNREFUSED xxx.xxx.xxx.xxx:443

或者

npm ERR! network timeout at: https://registry.npmjs.org/xxx

这里的 xxx 可能是您要发布包的某个依赖项，或者是 Verdaccio 自身尝试查询的元数据，核心问题在于，即使您的 .npmrc 文件已经正确配置为指向内部的 Verdaccio 地址（http://localhost:4873），在发布过程中，Verdaccio 服务器自身仍然会尝试向外部的 registry.npmjs.org 发起网络请求。

根源深析：Verdaccio 的代理机制

要理解这个问题，首先需要了解 Verdaccio 的核心工作模式，默认情况下，Verdaccio 不仅仅是一个简单的私有包存储，它更是一个智能的“代理”，当您请求一个包时,它会按以下顺序工作：

1. 检查本地存储：查看该包是否已存在于自己的存储中。
2. 检查上游链接：如果本地没有，它会查看配置文件中定义的 uplinks（上游链接），并尝试从这些上游源（默认为 https://registry.npmjs.org/）获取包。
3. 缓存并返回：从上游成功获取后，会将其缓存在本地,然后返回给请求者。

在 npm publish 的过程中，Verdaccio 会执行一些校验操作，它可能会尝试检查您要发布的包所声明的依赖项（dependencies、peerDependencies 等）的最新版本信息，或者验证包的元数据，这个“检查”动作，正是触发它向外网 registry.npmjs.org 发起请求的原因，在离线环境下，这个请求自然会失败,从而导致整个发布流程中断。

核心解决方案：修改 Verdaccio 配置

解决此问题的关键在于告诉 Verdaccio：“你现在处于离线模式，不要再尝试连接任何外部服务器了。” 这需要通过修改其核心配置文件 config.yaml 来实现。

定位并编辑 config.yaml

该文件通常位于 Verdaccio 的安装目录下的 conf 文件夹中，或者通过环境变量 VERDACCIO_CONFIG_PATH 指定。

禁用上游链接和代理设置

打开 config.yaml 文件，我们需要关注两个主要部分：uplinks 和 packages。

1. 处理 uplinks
   这个部分定义了 Verdaccio 的上游服务器，在离线模式下,最直接的方法是将其注释掉或删除。

   # 原始配置
   uplinks:
     npmjs:
       url: https://registry.npmjs.org/
   # 修改为离线配置（注释掉）
   # uplinks:
   #   npmjs:
   #     url: https://registry.npmjs.org/

2. 
   packages 部分定义了不同包的访问和发布权限，每个匹配规则下可能都有一个 proxy 属性，它指定了该规则的包应该使用哪个 uplink，为了彻底断开与外网的连接，需要将所有 proxy 设置移除或设为 null。

   # 原始配置可能如下
   packages:
     '@*/*':
       access: $all
       publish: $authenticated
       proxy: npmjs  # <-- 这里指定了代理
     '**':
       access: $all
       publish: $authenticated
       proxy: npmjs  # <-- 这里也指定了代理
   # 修改为离线配置
   packages:
     '@*/*':
       access: $all
       publish: $authenticated
       # proxy: npmjs  <-- 注释或删除此行
     '**':
       access: $all
       publish: $authenticated
       # proxy: npmjs  <-- 注释或删除此行

通过以上修改，我们实质上是告诉 Verdaccio：不再定义任何上游服务器，并且对于所有包的请求，都不要尝试去代理获取，这样，Verdaccio 就会完全依赖其本地存储进行工作,成为一个纯粹的离线私有仓库。

重启 Verdaccio 服务

配置文件修改完成后，必须重启 Verdaccio 服务才能使更改生效，如果您是使用 pm2 或 systemd 管理服务,请执行相应的重启命令。

# 使用 pm2 重启
pm2 restart verdaccio

验证配置与重新发布

重启后，再次尝试 npm publish，您应该会发现发布过程不再尝试连接外网，能够成功将包发布到您的私有 Verdaccio 仓库中，可以观察 Verdaccio 的日志输出，确认没有产生任何指向 registry.npmjs.org 的网络请求错误。

补充策略：依赖项预缓存

在某些复杂的场景下，您的项目可能依赖一些同样在内网中发布的私有包，确保这些依赖包也已经成功发布到离线的 Verdaccio 仓库中至关重要，如果依赖项缺失，虽然 npm publish 本身可能成功（因为 Verdaccio 不再检查依赖），但后续其他项目 npm install 您发布的这个包时就会失败，最佳实践是：在进入离线环境前，先将所有必需的公共和私有依赖项都安装一次，让 Verdaccio 的缓存机制将它们完整地存储下来。

---

相关问答 FAQs

问：在完全离线模式下，如何管理和更新包的依赖项？

答： 在完全离线模式下，依赖项管理需要提前规划，主要有两种策略：第一，预缓存策略，即在断开网络连接前，通过 npm install <package-name> 或 npm cache add <package-name>@<version> 命令，将所有可能用到的依赖项拉取到 Verdaccio 的缓存中，这样，即使离线，其他项目也能从 Verdaccio 缓存中安装这些依赖，第二，全私有化策略，将所有第三方依赖项也作为私有包发布到内部的 Verdaccio 仓库中，这种方式更可控，但初期工作量较大,需要建立一套将公共包导入内部仓库的流程。

问：我能否配置 Verdaccio，使其一部分包走代理（在线），另一部分包完全离线？

答： 是的，完全可以，Verdaccio 的 packages 配置支持基于包名模式的精细化控制，您可以创建不同的规则来匹配不同的包，您可以配置所有 @company/* 命名的内部包完全不使用代理，而其他所有公共包则继续通过 npmjs 上游代理,配置示例如下：

uplinks:
  npmjs:
    url: https://registry.npmjs.org/
packages:
  # 公司内部包，不代理，完全离线
  '@company/*':
    access: $all
    publish: $authenticated
    # 没有 proxy 属性
  # 其他所有包，使用 npmjs 代理
  '**':
    access: $all
    publish: $authenticated
    proxy: npmjs

这种混合模式非常适合那些部分业务需要访问外网,而另一部分核心业务必须严格隔离的网络环境。