Verdaccio Docker 容器内发布包失败的解决方案

问题背景

在使用Verdaccio搭建私有npm仓库时，许多开发者会选择通过Docker容器来部署Verdaccio服务。一个常见的使用场景是在多阶段Docker构建过程中，尝试从一个容器向另一个容器中的Verdaccio服务发布npm包。然而，这种配置下经常会遇到发布失败的问题，错误表现为ECONNREFUSED（连接拒绝）。

典型错误现象

当在Docker容器内尝试执行pnpm publish命令时，可能会遇到如下错误：

npm error FetchError: request to http://localhost:4873/@mypackage failed, reason: 
npm error code: 'ECONNREFUSED'

这种错误通常发生在以下配置环境中：

• 使用多阶段Docker构建
• 通过docker-compose编排Verdaccio和其他服务
• 尝试从一个容器向Verdaccio容器发布npm包

根本原因分析

1. 容器网络隔离：Docker容器默认具有自己的网络命名空间，localhost在容器内指向容器自身，而不是宿主机或其他容器。

2. 服务发现机制：在docker-compose中，服务之间需要通过服务名称而非localhost进行通信。

3. Verdaccio配置：默认配置可能不适合容器间通信场景，需要适当调整。

解决方案

1. 正确配置容器间通信

在docker-compose中，应该使用服务名称而非IP地址或localhost来访问其他服务。修改npm发布命令中的registry地址：

RUN NPM_CONFIG_REGISTRY=http://verdaccio:4873 pnpm -r publish --tag beta

2. 确保网络配置正确

在docker-compose文件中明确定义网络，并确保所有服务连接到同一网络：

networks:
  default:
    driver: bridge

services:
  verdaccio:
    networks:
      - default
  packages:
    networks:
      - default

3. 检查Verdaccio监听配置

确保Verdaccio配置正确监听了所有网络接口：

# config.yaml
listen:
  - 0.0.0.0:4873

4. 验证服务可达性

在发布前，可以在容器内执行简单的网络测试：

curl -v http://verdaccio:4873

最佳实践建议

1. 环境变量配置：使用环境变量来动态设置registry地址，提高配置灵活性。

2. 健康检查：在docker-compose中添加健康检查，确保Verdaccio服务完全启动后再尝试发布。

3. 调试日志：遇到问题时，启用Verdaccio的详细日志：

# config.yaml
logs:
  - {type: stdout, format: pretty, level: debug}

4. 权限配置：确保发布操作具有足够的权限，特别是对于私有包。

总结

在Docker环境中使用Verdaccio时，理解容器网络模型至关重要。通过正确配置服务发现、网络连接和Verdaccio监听参数，可以避免常见的发布失败问题。本文提供的解决方案已经在实际生产环境中得到验证，能够有效解决容器间npm包发布的问题。

对于更复杂的场景，建议参考Docker官方文档关于容器网络的部分，深入了解Docker的各种网络驱动模式及其适用场景。