告別 MAMP/XAMPP 惡夢！資深工程師的 Docker + WP-CLI + Xdebug 本地開發環境終極指南

嗨，我是浪花科技的 Eric。身為一個在 WordPress 世界打滾多年的工程師，最常聽到的經典名句，大概就是那句「在我電腦明明可以跑的啊？」。你是否也曾遇過，在你電腦上精心調整、完美無瑕的佈景主題，一上傳到客戶的主機就版面全毀？或是團隊新來的夥伴，光是搞定本機的 PHP、MySQL 版本就耗掉一整天，專案進度直接卡關？

坦白說，這些傳統開發工具如 MAMP、XAMPP、Laragon 等，雖然方便入門，但在團隊協作和環境一致性上，簡直是一場災難。今天，我就要帶你徹底告別這些惡夢，導入現代化的 Docker 容器化部署教學，打造一個專業、高效、且「到哪都能跑」的 WordPress 本地開發環境。這不只是一個工具的轉換，更是開發思維的升級！

為什麼你的 WordPress 開發流程需要 Docker？

在我們動手之前，讓我們先囉嗦一下，為什麼要自找麻煩學 Docker？直接用 MAMP 按個鈕啟動不是很快嗎？快，但不穩、不專業。

傳統開發方式的痛點

• 環境不一致：你用 PHP 7.4，同事用 PHP 8.1，正式主機用 PHP 8.0，光是版本差異就可能引發一堆莫名其妙的 bug。
• 系統污染：在本機安裝各種版本的資料庫、伺服器軟體，不僅佔用資源，移除時還可能清不乾淨，把你的開發機搞得一團亂。
• 協作困難：新成員加入專案，光是環境設定就要看好幾頁的文件，還不一定能成功複製出一模一樣的環境。
• 無法模擬生產環境：本地環境和正式主機的設定（如 Nginx vs. Apache、資料庫版本）差異過大，導致「本機正常，線上爆炸」的慘劇一再上演。

Docker 如何解決這一切？

Docker 就像一個個輕巧的「貨櫃」，你可以把 WordPress 核心、資料庫（MariaDB/MySQL）、PHP 環境等所有需要的服務，都打包在各自獨立的貨櫃裡。透過一個設定檔（docker-compose.yml），就能一鍵啟動整個網站應用程式。

• 環境一致性：團隊每個人都使用同一個設定檔，確保開發、測試、生產環境完全一致，根除「在我電腦可以跑」的問題。
• 隔離與純淨：每個專案都在獨立的容器中運行，互不干擾，你的本機系統永遠保持乾淨。
• 快速部署：新人加入，只需要安裝 Docker，執行一行指令，幾分鐘內就能擁有完整的開發環境。
• 可攜性：整個應用程式被「容器化」了，可以輕易地在任何支援 Docker 的機器上運行，從你的筆電到雲端主機都一樣。

囉嗦完了，是不是覺得該動手了？這才是專業 WordPress 開發該有的樣子！

實戰開始：打造你的終極 docker-compose.yml

docker-compose.yml 是我們整個 Docker 工作流程的核心，它定義了我們的應用程式需要哪些服務，以及這些服務如何協同工作。來，我們直接看一個專為 WordPress 開發設計的範例。

步驟一：建立專案結構

首先，在你的電腦上建立一個新的專案資料夾，例如 my-wp-project。然後在裡面建立一個名為 docker-compose.yml 的檔案，以及一個用來存放 WordPress 檔案的 src 資料夾。

my-wp-project/
├── docker-compose.yml
└── src/

步驟二：撰寫 docker-compose.yml

將以下內容貼到你的 docker-compose.yml 檔案中。別擔心，我會逐一解釋每個設定的意義。

version: '3.8'

services:
  db:
    image: mariadb:10.6
    container_name: my_wp_db
    restart: unless-stopped
    environment:
      MYSQL_ROOT_PASSWORD: "somestrongpassword"
      MYSQL_DATABASE: "wordpress"
      MYSQL_USER: "wordpress_user"
      MYSQL_PASSWORD: "wordpress_password"
    volumes:
      - db_data:/var/lib/mysql
    networks:
      - wp_network

  wordpress:
    image: wordpress:latest
    container_name: my_wp_app
    restart: unless-stopped
    ports:
      - "8080:80"
    environment:
      WORDPRESS_DB_HOST: db:3306
      WORDPRESS_DB_USER: "wordpress_user"
      WORDPRESS_DB_PASSWORD: "wordpress_password"
      WORDPRESS_DB_NAME: "wordpress"
      WORDPRESS_DEBUG: 1
    volumes:
      - ./src:/var/www/html
    depends_on:
      - db
    networks:
      - wp_network

volumes:
  db_data:

networks:
  wp_network:
    driver: bridge

設定檔解析

• services: 定義我們需要的服務容器。這裡我們有 db（資料庫）和 wordpress（網站應用）。
• db 服務:
  • image: mariadb:10.6: 指定使用 MariaDB 10.6 版本的官方映像檔。
  • environment: 設定環境變數，用來初始化資料庫，如 root 密碼、資料庫名稱、使用者等。千萬不要在正式環境用這麼簡單的密碼！
  • volumes: - db_data:/var/lib/mysql: 這是關鍵！它會將容器內的 /var/lib/mysql 資料夾（資料庫實際儲存位置）掛載到一個名為 db_data 的 Docker Volume。這樣即使你刪除容器，資料庫的資料也會被保留下來。
• wordpress 服務:
  • image: wordpress:latest: 使用最新的官方 WordPress 映像檔。
  • ports: - "8080:80": 將我們本機的 8080 連接埠，對應到容器內的 80 連接埠。這樣我們就能透過瀏覽器訪問 http://localhost:8080 來看到網站。
  • environment: 設定 WordPress 連接資料庫所需的資訊。注意 WORDPRESS_DB_HOST 設為 db:3306，db 就是我們上面定義的資料庫服務名稱。Docker Compose 會自動處理內部的 DNS 解析。
  • volumes: - ./src:/var/www/html: 另一個關鍵！這會將我們本機的 src 資料夾，完整對應到容器內的網站根目錄 /var/www/html。這意味著你在本機用 VS Code 等編輯器對 src 裡的檔案做任何修改，都會「即時」反映在容器裡的網站上，這就是我們實現 Live Coding 的魔法！
  • depends_on: - db: 告訴 Docker，wordpress 服務必須在 db 服務成功啟動後才能啟動。

現在，在你的終端機 (Terminal) 裡，進入 my-wp-project 資料夾，然後執行：

docker-compose up -d

等它跑完後，打開瀏覽器，訪問 http://localhost:8080，你應該就能看到熟悉的 WordPress 安裝畫面了！恭喜你，你的現代化開發環境已經成功啟動！

開發流程大升級：善用 WP-CLI 與 Xdebug

只把網站跑起來還不夠，專業的開發者需要更強大的工具來提升效率。這就是 WP-CLI 和 Xdebug 登板救援的時刻了。

在容器內執行 WP-CLI

還在用滑鼠點擊後台安裝外掛、建立使用者嗎？太慢了！WP-CLI (WordPress Command-Line Interface) 讓我們能用指令稿定一切。要在容器裡執行它非常簡單：

docker-compose exec wordpress wp <command>

docker-compose exec 指令讓我們可以在正在運行的容器內執行命令。wordpress 是我們的服務名稱，後面接的就是你想執行的任何 WP-CLI 指令。

• 安裝並啟用外掛：

  docker-compose exec wordpress wp plugin install classic-editor --activate

• 查看外掛列表：

  docker-compose exec wordpress wp plugin list

• 建立一個測試使用者：

  docker-compose exec wordpress wp user create testuser test@example.com --role=administrator --user_pass=password

是不是很有效率？把常用的指令寫成 shell script，一鍵就能初始化好整個開發網站！

啟用 Xdebug 進行斷點除錯 (Debugging)

var_dump() 和 die() 是開發初期的好朋友，但要處理複雜的邏輯或追蹤核心 bug，沒有斷點除錯就像矇著眼睛開車。要在 Docker 環境中設定 Xdebug 需要多一點步驟，但絕對值得。

首先，我們需要建立一個自訂的 Dockerfile 來擴展官方的 WordPress 映像檔，並在裡面安裝 Xdebug。然後，我們需要一個 php.ini 設定檔。

1. 建立設定檔

在你的專案根目錄下，建立一個 docker 資料夾，並在裡面新增 Dockerfile 和 php.ini 兩個檔案。

my-wp-project/
├── docker/
│   ├── Dockerfile
│   └── php.ini
├── docker-compose.yml
└── src/

docker/Dockerfile:

FROM wordpress:latest

# Install Xdebug
RUN pecl install xdebug && docker-php-ext-enable xdebug

docker/php.ini:

xdebug.mode = debug
xdebug.start_with_request = yes
xdebug.client_host = host.docker.internal
xdebug.client_port = 9003
xdebug.log = /tmp/xdebug.log
xdebug.idekey = VSCODE

host.docker.internal 是一個神奇的 DNS 名稱，它會指向運行 Docker 的主機 IP，讓容器內的 Xdebug 能夠「回頭」找到你本機的 VS Code。

2. 修改 docker-compose.yml

接著，修改 docker-compose.yml 裡的 wordpress 服務，讓它使用我們自訂的 Dockerfile 來建構映像檔，並載入 php.ini 設定。

# ... (其他設定不變)

  wordpress:
    build: ./docker # 改用 build 而非 image
    container_name: my_wp_app
    restart: unless-stopped
    ports:
      - "8080:80"
    environment:
      # ... (環境變數不變)
    volumes:
      - ./src:/var/www/html
      - ./docker/php.ini:/usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini # 掛載 php.ini
    depends_on:
      - db
    networks:
      - wp_network

# ... (其他設定不變)

3. 重新建構並啟動

因為我們修改了 Dockerfile，需要告訴 Docker Compose 重新建構映像檔。

docker-compose up -d --build

最後，在你的 VS Code 中安裝 PHP Debug 擴充功能，並設定好 launch.json 來監聽 9003 連接埠。現在，你可以在你的 PHP 程式碼中設定斷點，重新整理網頁，就能享受專業的斷點除錯功能了！再也不用滿天下的 echo 和 var_dump。如果你在除錯時遇到困難，可以參考這篇更全面的 WordPress 偵錯終極指南。

結論：擁抱現代化開發流程

從傳統的 MAMP/XAMPP 轉換到 Docker，初期可能需要一點學習曲線，但它帶來的好處是巨大的。一個穩定、一致、可攜、且高效的開發環境，能讓你專注在真正重要的事情上——也就是撰寫高品質的程式碼和打造出色的網站。

今天我們從頭打造了一個包含 Docker Compose、WP-CLI 和 Xdebug 的 WordPress 本地開發環境。這套流程不僅適用於個人專案，更能無縫擴展到整個開發團隊，徹底解決環境不一致的協作惡夢。希望這份Docker 容器化部署教學，能幫助你邁向更專業的 WordPress 開發者之路。

如果你覺得這個設定很棒，但還是覺得有點複雜，或是有更進階的需求，例如導入 CI/CD 自動化部署、或是針對高流量網站進行 Docker 效能調校，別忘了，浪花科技的團隊隨時在這裡提供協助。

覺得設定 Docker 環境還是太複雜，或是有更進階的 WordPress 開發、網站效能優化需求嗎？立即聯繫浪花科技，讓我們的資深工程師團隊為您打造穩定、高效的網站解決方案！

推薦閱讀

• 「在我電腦明明可以跑的?」WordPress Docker 容器化部署終極教學
• 終結滑鼠手！資深工程師的 WP-CLI 神兵利器，讓你的 WordPress 管理效率原地起飛！
• 網站又掛了？別再瞎猜！資深工程師的 WordPress 偵錯終極指南，從「死亡白畫面」到效能瓶頸全搞定！