Verdaccio离线publish报错如何解决？

Verdaccio 离线 Publish 报错：深度解析与实战解决方案

场景重现： 当你信心满满地在断网环境（或目标 Verdaccio 服务不可达）中执行 npm publish，期待包顺利发布到本地搭建的 Verdaccio 私有仓库时,终端却无情地抛出了类似错误：

npm ERR! code E404
npm ERR! 404 Not Found - PUT http://registry.npmjs.org/-/user/org.couchdb.user:your_username
npm ERR! 404
npm ERR! 404  'org.couchdb.user:your_username' is not in this registry
npm ERR! 404
npm ERR! 404 Note that you can also install from a
npm ERR! 404 tarball, folder, http url, or git url.

或者

npm ERR! code E500
npm ERR! 500 Internal Server Error - PUT http://your-verdaccio:4873/your-package

明明 Verdaccio 就在本地运行，为何发布请求似乎试图连接 registry.npmjs.org（npm 官方仓库）？核心矛盾浮现：Verdaccio 的默认行为要求在线进行用户认证。

核心根源剖析：

1. 用户认证的默认在线依赖： Verdaccio 默认配置 (config.yaml) 使用内置的 htpasswd 插件管理用户，关键点在于：执行 npm adduser 或 npm login 以及首次 npm publish（需要认证时），Verdaccio 默认会将用户认证请求 代理转发至上游仓库（通常是 https://registry.npmjs.org/），这是设计使然，目的是复用 npm 官方用户体系或企业统一认证源。

   auth:
     htpasswd:
       file: ./htpasswd
       # 默认 max_users 为 1000，允许用户自助注册，设置为 -1 禁用注册。

   当你的环境完全离线或无法访问上游 registry.npmjs.org 时，这个认证请求必然失败，导致 npm publish 因无法验证用户身份而报错。

2. 包元数据完整性校验（次要因素）： 在发布包时，npm 客户端会尝试获取上游仓库中该包的最新元数据信息，用于校验版本冲突等，如果完全离线且本地 Verdaccio 从未缓存过该包，这个请求也会失败，虽然这通常不会直接导致 E404 主错误,但可能叠加在其他错误信息中。

实战解决方案：构建真正的离线发布能力

启用 offline 模式（临时/推荐）

这是 最快捷、侵入性最小 的解决方案,尤其适合临时性离线发布。

• 原理： 通过 npm config set 命令或 .npmrc 文件，强制 npm 客户端在发布时 跳过所有用户认证和元数据完整性检查，直接将包推送到指定的 registry URL。
• 操作步骤：
  1. 确保目标 Verdaccio 服务已启动且本地可达。
  2. 在需要执行 npm publish 的项目目录下或用户级/全局配置中，设置 npm 的离线发布标志：

     npm config set offline true
     # 或者，在项目根目录创建/修改 .npmrc 文件，添加：
     # offline=true

  3. 执行发布命令 (确保 registry 指向你的 Verdaccio):

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

• 优点： 配置简单，无需修改 Verdaccio 服务端,适合短时离线。
• 缺点： 跳过认证意味着任何能访问该 Verdaccio 服务的人都可以发布（需结合防火墙/IP白名单等）,跳过元数据校验需自行确保版本号管理。

配置 Verdaccio 完全离线认证（永久）

此方案修改 Verdaccio 服务端配置，使其 在用户认证环节完全不依赖任何上游,实现彻底的离线运行。

• 原理： 修改 config.yaml，让 htpasswd 插件管理本地用户文件 (./htpasswd)，并 禁用所有上游代理。

• 操作步骤：

  

  1. 停止 Verdaccio 服务。

  2. 编辑 Verdaccio 的 config.yaml 文件 (通常位于安装目录或 ~/.config/verdaccio 或 /etc/verdaccio)。

  3. 关键配置修改：

     # 禁用所有上游仓库代理 (uplinks 置空)
     uplinks: {}
     # 配置 auth 仅使用本地 htpasswd，并明确设置 max_users: -1 禁止通过 npm adduser 注册（需手动创建用户）
     auth:
       htpasswd:
         file: ./htpasswd
         max_users: -1  # 禁止自助注册
     # packages 配置中，移除代理设置 '@*/*' 的代理路径（如果有）
     packages:
       '@*/*':
         # access: $all
         # publish: $authenticated
         # proxy: npmjs  # 注释掉或删除此行，确保不代理
       '**':
         access: $all
         publish: $authenticated
         # proxy: npmjs  # 注释掉或删除此行，确保不代理

  4. 手动创建用户： 因为禁用了注册 (max_users: -1)，需要手动在 Verdaccio 服务器上使用 htpasswd 工具创建用户：

     # 进入 Verdaccio 数据目录 (通常包含 config.yaml 和 storage)
     cd /path/to/verdaccio
     # 使用系统 htpasswd 或 docker 容器内工具创建用户 (username 替换为你的用户名)
     htpasswd -c ./htpasswd username  # -c 仅在第一次创建文件时使用
     # 输入并确认密码

  5. 启动 Verdaccio 服务。

  6. 在客户端，使用 npm login 登录到你的 Verdaccio (地址 http://localhost:4873),输入手动创建的用户名密码。

  7. 正常执行 npm publish --registry http://localhost:4873,此时认证请求完全在本地处理。

• 优点： 实现 Verdaccio 完全离线自治，用户管理本地化,安全性可控。

• 缺点： 配置稍复杂，需要手动管理用户账户,失去了与上游统一认证的便利性。

搭建内部镜像或缓存上游（高可用推荐）

对于需要长期稳定离线或受限网络环境（如内网开发），最佳实践是 在可联网区域搭建一个能完全缓存所需包的 Verdaccio 镜像,然后让离线环境通过此镜像同步。

• 原理： 配置一个 Verdaccio 实例，其 uplinks 指向官方 npmjs 或其他所需源，并设置 maxage 缓存策略，确保该实例能定期联网更新缓存，离线环境的 Verdaccio 再以此镜像作为自己的 uplink。
• 操作简述：
  1. 镜像节点 (Mirror)： 在可联网区部署 Verdaccio，config.yaml 配置强缓存 (maxage)。

     uplinks:
       npmjs:
         url: https://registry.npmjs.org/
         maxage: 48h # 缓存时间，根据需求调整
     packages:
       '**':
         access: $all
         publish: $authenticated
         proxy: npmjs # 所有包请求代理到 npmjs 并缓存

  2. 离线节点 (Offline Verdaccio)： 在隔离网部署 Verdaccio，其 uplinks 指向内部的镜像节点。

     uplinks:
       internal-mirror:
         url: http://your-mirror-verdaccio:4873/ # 内部镜像地址
         # 可设置较长的 maxage 或 offline 模式（如果镜像稳定）
     auth:
       ... # 配置本地认证（如方案二）或指向镜像认证
     packages:
       '**':
         access: $all
         publish: $authenticated
         proxy: internal-mirror # 代理到内部镜像

  3. 用户在离线节点 npm login 和 npm publish，所有包请求（包括认证和元数据）首先尝试从内部镜像获取，镜像已有缓存则直接返回，无需访问外网,发布操作直接提交到离线节点的存储。
• 优点： 最健壮的方案，平衡了离线需求和包的可用性/新鲜度,适合大型团队或严格网络管控环境。
• 缺点： 架构和运维相对复杂，需要维护至少两个 Verdaccio 实例。

诊断与调试关键点

• 查看 Verdaccio 日志： 运行 Verdaccio 时加上 --listen http://0.0.0.0:4873 --debug 参数或在 config.yaml 设置 logs: {type: stdout, format: pretty, level: debug},观察发布请求处理流程和错误详情。
• 检查 .npmrc： 确认执行 publish 命令时使用的 registry (npm config get registry) 是否正确指向目标 Verdaccio。
• 理解错误代码：
  • E404：通常指认证端点 (/-/user/org.couchdb.user:xxx) 或包路径在上游不存在（离线导致无法访问上游）。
  • E401：认证失败（密码错误或用户不存在）。
  • E500：Verdaccio 服务端内部错误（查看 Verdaccio 日志定位）。

经验之谈 Verdaccio 默认设计优先考虑与上游仓库的协作，这在联网环境下是优势，却成了离线发布的障碍，选择方案需权衡便利性与控制力：临时应急用 offline 模式最快；追求完全离线自治且用户少，手动配置 htpasswd 最彻底；大型团队或长期需求，投入搭建内部镜像架构最为可靠，理解认证流程和配置文件的联动，是驯服 Verdaccio 离线发布的关键，现代开发环境下，具备完善的离线支持能力,是保障研发流程不受网络波动影响的重要基础。