Node.js连接MySQL数据库报错排查与解决方案

一、问题/场景描述

在使用Node.js开发后端应用时，连接MySQL数据库是常见的操作。然而，开发者经常会遇到各种连接报错，例如“ECONNREFUSED”、“ER_NOT_SUPPORTED_AUTH_MODE”或“ER_ACCESS_DENIED_ERROR”等。这些错误会导致应用无法启动或数据库操作失败，影响开发进度。

二、原因分析

Node.js连接MySQL失败的原因多种多样，主要可以归结为以下几类：首先是网络与配置问题，如MySQL服务未启动、主机地址或端口错误、防火墙阻拦。其次是身份验证问题，例如用户名或密码错误，或者MySQL 8.0使用了新的默认身份验证插件（caching_sha2_password），而旧版Node.js驱动可能不支持。最后是依赖与代码问题，比如mysql或mysql2模块未正确安装，连接参数配置错误，或异步连接逻辑处理不当。

三、详细解决步骤

下面将按照从基础检查到针对性解决的顺序，详细介绍排查和解决步骤。

步骤1：检查MySQL服务状态与网络连通性

首先确保MySQL服务正在运行，并且可以从Node.js所在服务器访问。

# 检查MySQL服务状态（Linux/macOS）
sudo systemctl status mysql
# 或
sudo service mysql status

# 检查MySQL服务状态（Windows）
在服务管理中查看“MySQL”服务状态。

# 使用telnet测试端口连通性（如果telnet可用）
telnet localhost 3306

如果服务未运行，请启动它。如果无法连通，请检查防火墙设置，确保3306端口开放。

步骤2：验证数据库连接参数

确认你的Node.js代码中的连接配置（主机、端口、用户、密码、数据库名）完全正确。一个典型的连接示例如下：

const mysql = require('mysql2');
const connection = mysql.createConnection({
  host: 'localhost', // 确保是正确的主机名或IP
  port: 3306, // 确认端口
  user: 'your_username', // 确认用户名
  password: 'your_password', // 确认密码
  database: 'your_database' // 确认数据库存在
});

connection.connect((err) => {
  if (err) {
    console.error('连接失败：', err.message);
    return;
  }
  console.log('连接成功！');
});

建议先将密码等敏感信息写死进行测试，排除环境变量读取问题。

步骤3：处理MySQL 8.0身份验证插件问题

如果你使用的是MySQL 8.0+，并且错误信息包含“caching_sha2_password”，这是因为新版本默认使用了该插件。解决方案有两种：一是升级Node.js的MySQL驱动（推荐使用mysql2），它支持新插件；二是修改MySQL用户的身份验证方式。

-- 登录MySQL后，运行以下SQL更改用户验证方式
ALTER USER 'your_username'@'localhost' IDENTIFIED WITH mysql_native_password BY 'your_password';
FLUSH PRIVILEGES;

执行后，再次尝试Node.js连接。

步骤4：检查并安装正确的Node.js模块

确保已安装正确的数据库驱动模块。目前推荐使用mysql2，它性能更好且支持更多特性。

# 在项目目录下安装mysql2
npm install mysql2

同时，检查package.json中是否包含该依赖，并确保没有全局模块冲突。

步骤5：使用连接池并完善错误处理

对于生产环境或需要频繁连接的应用，建议使用连接池，并添加更详尽的错误监听。

const mysql = require('mysql2');
const pool = mysql.createPool({
  host: 'localhost',
  user: 'root',
  password: 'password',
  database: 'test',
  waitForConnections: true,
  connectionLimit: 10,
  queueLimit: 0
});

pool.getConnection((err, conn) => {
  if (err) {
    console.error('获取连接失败：', err.code, err.message);
    return;
  }
  console.log('从连接池获取连接成功！');
  conn.release(); // 将连接释放回连接池
});

四、注意事项

在排查过程中，请始终遵循安全规范，避免在最终代码中硬编码敏感信息，应使用环境变量或配置管理工具。修改MySQL用户认证插件会降低安全性，仅作为临时解决方案，长期而言应升级驱动以适应新的认证标准。处理异步连接时，注意使用Promise或async/await语法以避免回调地狱。

五、适用环境

本文介绍的方法适用于Node.js应用连接MySQL数据库时遇到的常见连接错误场景。