Docker Compose中Node.js连接MySQL容器报ECONNREFUSED错误

API 探路者

2026-8-30

解决方案

以下按问题出现概率从高到低排序，逐个排查即可：

90%概率为启动时序问题
depends_on配置仅能控制容器的拉起顺序，不会等待MySQL服务完成初始化。MySQL首次启动需要执行数据目录初始化、系统表加载、端口监听启动等流程，耗时数秒到数十秒不等，如果Node应用在MySQL完成3306端口监听前就发起连接，必然抛出ECONNREFUSED错误。你本地直接npm run dev能连通独立MySQL容器，本质是因为那个容器早就启动完成、处于服务就绪状态，不存在时序差问题。
两种修复方案选其一即可：

应用层加重试逻辑（官方推荐，容错性最高）
在数据库连接逻辑中加失败重试，不要依赖容器层面的启动顺序控制，参考代码：

// db.js 连接逻辑示例，以mysql2/sequelize为例
const maxRetries = 15
const retryDelay = 2000

async function connectDB(retries = maxRetries) {
  try {
    await connection.connect() // 替换为你实际使用的连接方法，比如sequelize.authenticate()
    console.log('数据库连接成功')
  } catch (err) {
    if (retries > 0) {
      console.log(`连接失败，${retryDelay/1000}s后重试，剩余重试次数：${retries - 1}`)
      setTimeout(() => connectDB(retries - 1), retryDelay)
    } else {
      console.error('重试耗尽，数据库连接失败', err)
      process.exit(1)
    }
  }
}

connectDB()

编排层加健康检查控制启动顺序
给MySQL服务配置健康检查，让compose等待MySQL真正就绪后再启动Node服务，修改docker-compose.yml参考配置：

services:
  mysql:
    image: mysql:8.0 # 保留你原有镜像、环境变量、数据卷配置
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "127.0.0.1", "-uroot", "-p${MYSQL_ROOT_PASSWORD}"]
      interval: 2s
      timeout: 3s
      retries: 20
  node-app:
    # 保留你原有build、端口映射、环境变量配置
    depends_on:
      mysql:
        condition: service_healthy

检查MySQL监听地址配置
如果你自定义了MySQL的my.cnf配置，确认没有bind-address = 127.0.0.1的配置项，该项会导致MySQL仅监听环回地址，拒绝其他容器的访问请求，需要改成bind-address = 0.0.0.0。官方MySQL镜像默认已经配置为监听所有地址，仅挂载自定义配置时需要排查该项。
检查连接配置正确性
不要在Node的数据库连接参数中手动写死MySQL容器IP，容器重建后IP会变动，直接把数据库主机地址填为compose中MySQL服务的服务名（比如你MySQL服务名叫mysql就填mysql），compose内置DNS会自动解析到正确的容器IP。另外注意连接端口填容器内部的MySQL默认端口3306，不要填你映射到宿主机的对外端口（比如你把MySQL映射到宿主机33060，容器内部连接还是用3306）。
连通性验证
两个容器都启动后，执行docker exec -it <node容器ID/名称> sh进入Node容器，安装netcat后执行nc -zv mysql 3306，如果返回端口开放成功提示说明网络层面连通，问题100%出在启动时序；如果提示连接失败，检查两个服务是否在同一个compose网络下，不要单独给某一个服务配置外部网络导致网络隔离。

内容的提问来源于stack exchange，提问作者AlexGA93