Django 本地環境整合 MySQL 完整教學 (含驅動安裝、配置避坑、驗證步驟)

前置條件

• 已安裝 MySQL Server (本文以 5.6/5.7 為例)。
• 已建立 Django 專案 (版本 1.4~2.x 均適用，核心配置不變)。
• 作業系統：macOS / Linux / Windows 均可，命令略有差異。

步驟 1：建立資料庫與用戶

進入 MySQL 客戶端：

# macOS/Linux (假設已配置 PATH)
mysql -u root -p
# Windows (進入安裝目錄 bin 下)
mysql.exe -u root -p

執行 SQL：

CREATE DATABASE myproject_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'django_user'@'localhost' IDENTIFIED BY 'strong_password';
GRANT ALL PRIVILEGES ON myproject_db.* TO 'django_user'@'localhost';
FLUSH PRIVILEGES;

重點：必須先建立資料庫，Django migrate 不會自動建庫。

步驟 2：修改 settings.py 資料庫配置

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.mysql',
        'NAME': 'myproject_db',          # 步驟 1 建立的資料庫名
        'USER': 'django_user',           # 步驟 1 建立的用戶
        'PASSWORD': 'strong_password',   # 步驟 1 設定的密碼
        'HOST': '127.0.0.1',             # 本機用 127.0.0.1 (TCP)，非 localhost (Unix Socket)
        'PORT': '3306',                  # 預設埠，可省略
        'OPTIONS': {
            'charset': 'utf8mb4',        # 關鍵：支援 Emoji 與生僻字
            'init_command': "SET sql_mode='STRICT_TRANS_TABLES'",  # 建議開啟嚴格模式
        },
    }
}

關鍵參數說明

• HOST：建議用 127.0.0.1。若用 localhost，Django 驅動會嘗試 Unix Socket 連線，權限/路徑問題較多。
• OPTIONS.charset：務必設為 utf8mb4，對應 MySQL 端 utf8mb4，否則存 Emoji 會報錯。
• init_command：設定 SQL 模式，避免資料截斷靜默發生。

步驟 3：安裝 Python MySQL 驅動

Django 官方推薦 mysqlclient (C 語言編譯，效能最佳，支援 Python 3)。

# macOS (需先安裝 MySQL client library)
brew install mysql-client
export PATH="/usr/local/opt/mysql-client/bin:$PATH"
pip install mysqlclient

# Ubuntu/Debian
sudo apt-get install python3-dev default-libmysqlclient-dev build-essential
pip install mysqlclient

# Windows (預編譯 wheel)
pip install mysqlclient
# 若報錯嘗試
pip install --only-binary :all: mysqlclient

舊版驅動：MySQL-python (Python 2 only, 已停維護)、pymysql (純 Python, 效能較差，需 pymysql.install_as_MySQLdb() 猴子補丁)。**生產環境強烈建議 mysqlclient**。

步驟 4：驗證連線與遷移

# 進入專案目錄 (含 manage.py)
python manage.py check              # 檢查配置語法
python manage.py makemigrations     # 生成遷移檔
python manage.py migrate            # 執行遷移，建立表結構
python manage.py createsuperuser    # 建立管理員帳號 (可選)
python manage.py runserver          # 啟動開發伺服器驗證

常見錯誤與解決方案

進階：使用連線池 (生產環境推薦)

安裝 django-db-geventpool 或 django-mysql-pool，在 DATABASES['default'] 加入：

'ENGINE': 'django_mysqlpool.backends.mysqlpool',
'OPTIONS': {
    'MAX_CONNS': 20,
    'RECYCLE': 3600,
}

總結檢查清單

1. ✅ MySQL 建庫 utf8mb4、建用戶授權。
2. ✅ settings.py 配置 HOST=127.0.0.1、charset=utf8mb4。
3. ✅ pip install mysqlclient 成功 (系統依賴已裝)。
4. ✅ migrate 無錯誤、runserver 正常訪問。