環境準備

1. 安裝 MySQL 服務

前往 MySQL 官網 下載對應作業系統的安裝包。macOS 可使用 Homebrew：

brew install mysql
brew services start mysql

安裝完成後，預設 root 密碼為空，建議立即設定密碼：

mysqladmin -u root password 'your_strong_password'

2. 圖形化管理工具推薦

• MySQL Workbench：官方免費工具，功能完整
• TablePlus：輕量級、跨平台、介面優雅
• DBeaver：開源通用資料庫客戶端

Node.js 專案整合 MySQL

1. 初始化專案並安裝驅動

現代專案推薦使用 mysql2（支援 Promise/Async-Await）或 Prisma（ORM）：

npm init -y
npm install mysql2
# 或使用 ORM
npm install prisma @prisma/client
npx prisma init

2. 連線池配置最佳實踐

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

3. 現代化查詢寫法

// 查詢範例
const pool = require('./db');

async function getUsers() {
  try {
    const [rows] = await pool.query('SELECT id, name, email FROM users WHERE status = ?', ['active']);
    console.log('查詢結果:', rows);
    return rows;
  } catch (err) {
    console.error('查詢失敗:', err);
    throw err;
  }
}

// 事務範例
async function transferFunds(from, to, amount) {
  const conn = await pool.getConnection();
  try {
    await conn.beginTransaction();
    await conn.query('UPDATE accounts SET balance = balance - ? WHERE id = ?', [amount, from]);
    await conn.query('UPDATE accounts SET balance = balance + ? WHERE id = ?', [amount, to]);
    await conn.commit();
  } catch (err) {
    await conn.rollback();
    throw err;
  } finally {
    conn.release();
  }
}

常見問題排查

錯誤現象	原因	解決方案
ER_ACCESS_DENIED_ERROR	帳號密碼錯誤或權限不足	確認認證資訊，授予對應資料庫權限
ECONNREFUSED	MySQL 服務未啟動或端口錯誤	檢查服務狀態，確認 3306 端口開放
ER_BAD_DB_ERROR	資料庫不存在	先建立資料庫或修正連線字串
PROTOCOL_ENQUEUE_AFTER_FATAL_ERROR	連線池耗盡或長連線斷開	調整 connectionLimit，啟用 ping 保活

效能優化建議

• 使用連線池避免頻繁建立/銷毀連線
• 啟用預處理語句防止 SQL 注入並提升效能
• 大量寫入時使用批次插入：INSERT INTO ... VALUES (...), (...), ...
• 適當添加索引，使用 EXPLAIN 分析慢查詢
• 監控慢查詢日誌，設定 long_query_time = 1

遷移舊專案（db-mysql）

若維護舊專案使用 db-mysql，建議逐步遷移至 mysql2：

1. 移除 export MYSQL_CONFIG=... 等環境變數設定
2. 將回調風格改寫為 Promise/Async-Await
3. 替換查詢建構器語法為標準 SQL

總結

Node.js 搭配 MySQL 開發已相當成熟，採用 mysql2 連線池與 Async-Await 寫法，能編寫出可維護、高效能的資料庫存取層。搭配 Prisma 等 ORM 更能提升開發效率與型別安全。