必须使用mysql2驱动并手动加载.env文件，通过连接池管理连接生命周期，避免硬编码凭据和单连接故障风险。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
在Cursor中开发Node.js项目时，直接连接MySQL数据库需要绕过IDE内置的终端限制、处理环境变量安全加载、避免硬编码凭据，并确保连接对象生命周期可控。你不能只复制粘贴教程代码就让数据库跑起来，因为Cursor默认不激活.env文件自动加载，且新建的Node.js进程不会继承编辑器启动时的环境变量。
安装mysql2驱动并初始化项目
打开Cursor内置终端（Ctrl+`），执行：
npm init -y → npm install mysql2
这一步必须用mysql2而非mysql。后者已停止维护，不支持Promise、prepare语句和现代认证插件（如caching_sha2_password），在MySQL 8.0+上会报错【ER_NOT_SUPPORTED_AUTH_MODE】。
创建安全连接配置
新建.env文件，写入：
DB_HOST=localhost
DB_USER=root
DB_PASSWORD=your_secure_password
DB_NAME=testdb
DB_PORT=3306
⚠️不要把密码写进JS文件。Cursor不会自动读取.env，必须手动加载——在index.js顶部加：
require('dotenv').config();
如果提示Cannot find module 'dotenv'，立刻运行npm install dotenv。这步漏掉，所有环境变量都是undefined，连接必然失败。
编写可复用的连接模块
创建db.js，内容如下：
const mysql = require('mysql2/promise');
const pool = mysql.createPool({
host: process.env.DB_HOST,
user: process.env.DB_USER,
password: process.env.DB_PASSWORD,
database: process.env.DB_NAME,
port: Number(process.env.DB_PORT),
waitForConnections: true,
connectionLimit: 10,
queueLimit: 0
});
module.exports = pool;
使用mysql2/promise路径导入，才能直接用await pool.execute()。连接池比单连接更可靠：单连接在查询出错后会断开，后续请求全部失败；而连接池自动重试、回收坏连接。
在路由或业务逻辑中执行查询
方法一：基础查询（适合简单CRUD）
const pool = require('./db');
async function getUser(id) {
const [rows] = await pool.execute('SELECT * FROM users WHERE id = ?', [id]);
return rows[0];
}
方法二：事务操作（需显式提交或回滚）
async function transfer(fromId, toId, amount) {
const connection = await pool.getConnection();
try {
await connection.beginTransaction();
await connection.execute('UPDATE accounts SET balance = balance - ? WHERE id = ?', [amount, fromId]);
await connection.execute('UPDATE accounts SET balance = balance + ? WHERE id = ?', [amount, toId]);
await connection.commit();
} catch (err) {
await connection.rollback();
throw err;
} finally {
connection.release();
}
}
注意connection.release()必须放在finally块里，否则连接泄露。池中连接数耗尽后，新请求会卡在getConnection()，超时抛PoolTimeoutError。
调试连接问题的三步定位法
第一步：检查MySQL服务是否运行
在Cursor终端执行mysql -u root -p，能登录说明服务正常；连不上就先启动MySQL（macOS用brew services start mysql，Windows查服务管理器）。
第二步：验证凭据是否被正确读取
在db.js里加一句console.log('DB_USER:', process.env.DB_USER);，运行node index.js，输出undefined即.env未生效。
第三步：捕获底层连接错误
给pool加错误监听：
pool.on('error', (err) => {
if (err.code === 'PROTOCOL_CONNECTION_LOST') {
console.error('数据库连接丢失，可能是MySQL重启或网络中断');
}
});
