NodeJs无法连接MySQL但服务器控制台可正常连接的问题排查

1. 强制Node.js使用IPv4连接 #

错误信息connect ECONNREFUSED ::1:3306表明Node.js客户端尝试通过IPv6地址::1连接MySQL，但MySQL未监听IPv6或未开放对应权限。直接将连接配置中的host从localhost改为127.0.0.1，强制走IPv4协议：

const connectDetails = {
  host: '127.0.0.1', // 替换localhost为IPv4本地地址
  user: process.env.DBUSER,
  password: process.env.DBPWD,
  database: "myshop",
  port: parseInt(process.env.DBPORT as string),
  debug: false,
};

也可以直接修改环境变量DBHOST的值为127.0.0.1。

2. 检查MySQL的绑定地址配置 #

登录MySQL控制台，执行以下命令查看当前绑定地址：

SHOW VARIABLES LIKE 'bind_address';

• 若结果为127.0.0.1：说明MySQL仅监听IPv4，不支持IPv6连接。若需同时支持IPv4和IPv6，编辑Ubuntu下的MySQL配置文件/etc/mysql/mysql.conf.d/mysqld.cnf，找到bind-address行并修改为：

  bind-address = ::
  

  修改后重启MySQL服务：

  sudo systemctl restart mysql
  

3. 补充MySQL用户的TCP连接权限 #

MySQL中myuser@localhost仅允许通过socket连接，而TCP/IP连接（无论IPv4还是IPv6）需要单独配置权限。执行以下SQL语句补充权限：

GRANT ALL PRIVILEGES ON myshop.* TO 'myuser'@'127.0.0.1' IDENTIFIED BY 'mypassword';
GRANT ALL PRIVILEGES ON myshop.* TO 'myuser'@'::1' IDENTIFIED BY 'mypassword';
FLUSH PRIVILEGES;

4. 验证MySQL端口监听状态 #

用ss命令检查MySQL是否在3306端口正常监听：

ss -tulpn | grep 3306

• 输出包含127.0.0.1:3306：仅IPv4监听
• 输出包含:::3306：同时监听IPv4和IPv6
• 无输出：MySQL服务未正常启动，需排查服务状态。

5. 显式指定Node.js客户端的IP协议版本 #

若使用mysql或mysql2包，可在连接配置中添加family字段强制指定IPv4：

const connectDetails = {
  host: process.env.DBHOST,
  user: process.env.DBUSER,
  password: process.env.DBPWD,
  database: "myshop",
  port: parseInt(process.env.DBPORT as string),
  debug: false,
  family: 4, // 强制使用IPv4协议
};

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