Node.js 20(LTS)升级后MariaDB npm远程连接超时问题

核心问题分析 #

错误ER_CONNECTION_TIMEOUT（错误码45012）表明客户端无法在默认的1001ms内与远程MariaDB建立socket连接，本地连接正常说明代码逻辑无基础问题，大概率是新版本驱动的默认配置变更或Node.js 20的网络行为调整导致。

排查与解决步骤 #

1. 增大连接超时阈值 #

mariadb npm v3.x将默认连接超时从旧版本的更长值调整为1000ms，远程网络延迟易触发超时。在Sequelize配置中手动指定更长的超时时间：

const sequelize = new Sequelize({
  dialect: 'mariadb',
  host: '远程服务器IP',
  port: 3306,
  username: '你的用户名',
  password: '你的密码',
  database: '目标数据库',
  dialectOptions: {
    connectTimeout: 5000 // 调整为5秒，可根据实际网络延迟修改
  }
});

2. 调整Node.js 20的DNS解析行为 #

Node.js 20默认启用了VERIFY_DNS_SERVER_CERTIFICATE，部分环境下会导致DNS解析延迟或失败，可通过以下方式调整：

• 环境变量启动：

  export NODE_OPTIONS="--dns-result-order=ipv4first --no-verify-dns-server-certificate"
  

• 代码内设置（需放在Sequelize初始化前）：

  process.env.NODE_OPTIONS = '--dns-result-order=ipv4first --no-verify-dns-server-certificate';
  

3. 适配mariadb v3.x的连接配置 #

新版本驱动对连接参数做了调整，确保配置无废弃项并显式指定网络参数：

dialectOptions: {
  socketPath: null, // 远程连接需设为null，避免本地socket路径干扰
  ssl: false, // 若远程未启用SSL，显式关闭（新版本可能默认检测SSL）
  connectTimeout: 5000,
  keepAlive: true, // 启用长连接保持机制
  keepAliveDelay: 30000
}

4. 验证远程服务器网络连通性 #

• 使用telnet 远程IP 3306或nc -zv 远程IP 3306测试端口是否开放
• 检查远程MariaDB配置文件my.cnf中bind-address是否允许客户端IP访问（可临时设为0.0.0.0测试）
• 确认服务器防火墙/安全组已放行3306端口

5. 临时降级驱动验证 #

若以上方法无效，可临时降级到原版本驱动确认是否为新版本兼容性问题：

npm uninstall mariadb
npm install mariadb@2.1.4

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