macOS 配置 PHP + MySQL 開發環境完整指南（原生 Apache + Homebrew 方案）

macOS 內建 Apache 與 PHP，但版本較舊且配置隱藏。現代開發建議使用 Homebrew 管理獨立版本，避免汙染系統環境。本文提供兩條路徑：快速啟用內建環境與Homebrew 專業環境，並涵蓋 MySQL、phpMyAdmin、虛擬主機與常見問題。

路徑一：快速啟用內建 Apache + PHP（適合臨時測試）

# 1. 編輯 Apache 設定
sudo vim /etc/apache2/httpd.conf

# 2. 取消註解 PHP 模組行
# LoadModule php_module libexec/apache2/libphp.so   (macOS 12+)
# LoadModule php5_module libexec/apache2/libphp5.so (舊版)

# 3. 啟用使用者 Sites 目錄（可選）
# 在 httpd.conf 找到 UserDir 相關設定，或建立 /etc/apache2/users/$(whoami).conf
# 內容：
# 
#   AllowOverride All
#   Require all granted
# 

# 4. 啟動 Apache
sudo apachectl start
# 或設定開機自動啟動
sudo launchctl load -w /System/Library/LaunchDaemons/org.apache.httpd.plist

# 5. 測試
# https://localhost/ 顯示 "It works!"
# https://localhost/~username/ 顯示 ~/Sites 內容

路徑二：Homebrew 專業環境（推薦長期開發）

# 1. 安裝 Homebrew (若未安裝)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 2. 安裝 PHP、MySQL、Nginx/Apache
brew install php@8.2 mysql nginx   # 可指定版本 php@7.4 等

# 3. 設定 PHP 為預設 CLI
echo 'export PATH="/opt/homebrew/opt/php@8.2/bin:/opt/homebrew/opt/php@8.2/sbin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# 4. 啟動服務 (brew services 需安裝 services tap)
brew services start php@8.2
brew services start mysql
brew services start nginx

# 5. 設定 MySQL root 密碼
mysql_secure_installation   # 互動式設定密碼、移除匿名用戶等

# 6. 安裝 phpMyAdmin (透過 Composer 或下載)
composer create-project phpmyadmin/phpmyadmin --repository-url=https://www.phpmyadmin.net/packages.json --no-dev
# 或下載壓縮包解壓至 Nginx 根目錄

# 7. 設定 Nginx 虛擬主機 (範例)
# /opt/homebrew/etc/nginx/servers/dev.conf
server {
    listen 80;
    server_name dev.local;
    root /Users/$(whoami)/Sites/public;
    index index.php index.html;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        fastcgi_pass 127.0.0.1:9000;  # PHP-FPM 預設埠
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }
}

# 8. 修改 /etc/hosts
echo "127.0.0.1 dev.local" | sudo tee -a /etc/hosts

# 9. 重載 Nginx
brew services restart nginx

常用工具與驗證

常見問題排查

1. PHP 版本切換：brew link --overwrite --force php@7.4 後 source ~/.zshrc。
2. MySQL 連線失敗：檢查 mysql.sock 路徑，php.ini 設定 pdo_mysql.default_socket 與 mysqli.default_socket。
3. 權限錯誤：Nginx/Apache 執行用戶需對專案目錄有讀取權限，chmod -R 755 /path/to/project。
4. phpMyAdmin 登入失敗：確認 config.inc.php 設定 $cfg['Servers'][$i]['host'] = '127.0.0.1'; 而非 localhost（Unix socket vs TCP）。

進階：Docker 替代方案

若專案需精確複現生產環境（特定 Linux 發行版、擴展版本），建議直接使用 docker-compose 管理 PHP-FPM、MySQL、Nginx、Redis 等容器，macOS 僅作為開發主機，環境一致性最高。

無論選擇內建快速啟用或 Homebrew 專業環境，掌握服務管理、虛擬主機配置、版本切換與除錯工具鏈，才能在 macOS 上獲得流暢的 PHP 開發體驗。