一句話破題

昨天我們用最原始的方式手動裝了 PHP 和 Composer，但老實說，日常開發沒有人想每次換專案就重新張羅 MySQL、Nginx、Redis 這些服務——今天介紹三種常見的本機開發方案：Laragon（Windows 一鍵整合環境）、Docker（容器化、跨平台的標準做法）、Laravel Sail（Laravel 官方包好的 Docker 輕量指令），外加一份 VS Code 的實用擴充套件清單，幫你選一套適合自己的組合。

Laragon：Windows 開發者的一鍵解法

如果你是 Windows 使用者，Laragon 大概是最省事的選擇。它把 PHP、Composer、Nginx、Apache、MySQL、Redis 整合成一個介面，裝一次之後可以隨時切換各軟體版本，不用個別操心。

安裝與基本設定

1. 到 laragon.org 下載完整版（Full 版已內建 PHP/Composer/Nginx/MySQL，比較省事）。
2. 安裝完成後開啟主介面，可以看到左側服務列表（Apache/Nginx、MySQL、Redis 等），點選即可啟動/停止。
3. Preferences 裡可以切換介面語系（含中文化）。
4. 右鍵選單有「PHP 版本切換」「快速產生新 Laravel 專案」等實用功能。

冷知識：Laragon 從 7 版起不再完全免費

這件事容易讓人措手不及，值得提前說清楚：Laragon 從 7 版開始走向付費授權。非商業用途雖然還能繼續免費使用，但啟動 Laragon 或啟動服務時會固定跳出授權提醒視窗，敦促你購買授權（最陽春的授權一次 10 美元起）；商業用途則明確要求要有授權才能使用。

如果你不想被這個提醒視窗打斷、也不想處理授權問題，官方的 6 版本身完全免費、不會有任何授權彈窗，可以直接到 GitHub 的 leokhoa/laragon releases 頁面找 6.x 版本下載——只是要注意 6 版已經被官方列為終止維護（EOL），不會再收到新版更新，如果你之後需要新版 PHP/MySQL 這類服務版本，可能得考慮升級到付費版或改用 Docker/Sail。

一鍵建立 Laravel 專案

Laragon 右鍵選單提供 Quick app，選擇 Laravel 就會自動跑 composer create-project laravel/laravel 幫你建好專案，並自動設定虛擬主機（專案名稱.test 網域），省去手動設定 Nginx/Apache 站台的麻煩。

Apache 還是 Nginx？

Laragon 兩種都能切換，這是老問題但答案沒變：Nginx 是事件驅動架構，處理高並發請求效能較好、資源消耗較低，目前是新專案的主流選擇（包含 Laravel Sail 預設用的就是 Nginx 家族）；Apache 設定較直覺、.htaccess 生態成熟，適合對 Apache 已經很熟悉、或需要用到特定 Apache 模組的情境。沒有特別理由的話，選 Nginx。

macOS 使用者的對應選擇：Herd

Laragon 是 Windows 專屬工具，如果你是 macOS 使用者，體驗最接近的選擇是 Laravel Herd——同樣是官方生態圈認可的一鍵整合環境，內建 PHP 多版本切換、自動網域（.test）、內建 Nginx。跟 Laragon 的差異是 Herd 走更「原生 macOS」的設計，用選單列圖示操作，Pro 版還額外提供本機 MySQL/Redis 管理、Xdebug 一鍵啟用、Dump 除錯工具（類似 dd() 但輸出到獨立視窗，不會打斷程式執行）。這系列不特別展開 Herd 的操作細節，但如果你是 Mac 用戶想要「Laragon 那種省事體驗」，Herd 是目前最對應的選項。

Docker：跨平台的標準答案

Laragon 很方便，但只支援 Windows，而且「在我電腦上可以跑」的環境不一致問題，用 Docker 才能真正解決——你的 Dockerfile 跟 docker-compose.yml 就是環境本身的定義，團隊每個人、甚至正式環境，跑起來都是同一套。

核心概念快速複習

• 映像檔（Image）：一個唯讀的環境範本，例如「裝好 PHP 8.3 + 特定擴充套件的 Linux 環境」。
• 容器（Container）：映像檔實際執行起來的實例，你可以同時開多個容器（例如同時跑 PHP 容器、MySQL 容器、Redis 容器）。
• Dockerfile：定義「怎麼從基礎映像檔組出你要的映像檔」的腳本。
• docker-compose.yml：定義「多個容器該怎麼一起啟動、怎麼互相連線」的設定檔，一個 Laravel 專案通常至少需要 PHP、資料庫兩個容器搭配使用。

一個最小可用的 docker-compose 範例

# docker-compose.yml
services:
    app:
        build:
            context: .
            dockerfile: Dockerfile
        volumes:
            - .:/var/www/html
        ports:
            - "8000:8000"
        depends_on:
            - db

    db:
        image: mysql:8.0
        environment:
            MYSQL_DATABASE: blog_app
            MYSQL_ROOT_PASSWORD: secret
        ports:
            - "3306:3306"
        volumes:
            - db_data:/var/lib/mysql

volumes:
    db_data:

# Dockerfile
FROM php:8.3-fpm

RUN apt-get update && apt-get install -y \
    unzip git libzip-dev \
    && docker-php-ext-install pdo pdo_mysql zip

COPY --from=composer:2 /usr/bin/composer /usr/bin/composer

WORKDIR /var/www/html

常用指令複習：

docker compose up -d      # 背景啟動所有服務
docker compose down       # 停止並移除容器
docker compose exec app bash   # 進入 app 容器的終端機
docker compose logs -f app     # 追蹤 app 容器的即時日誌
docker compose ps              # 查看目前有哪些容器在跑、狀態如何
docker compose restart app     # 只重啟單一服務，不需要整套 down/up

這套手動撰寫 Dockerfile 的方式，優點是完全掌控環境細節，缺點是門檻較高、每個新專案都要重新調整。如果你只是想快速把一個 Laravel 專案容器化，不想自己從頭寫 Dockerfile，這正是 Laravel Sail 要解決的問題。

![docker-compose 架構圖：瀏覽器透過 8000 port 存取 app 容器，app 容器掛載宿主機原始碼並透過 depends_on 連接 db 容器，db 容器資料存放在具名 volume]

上面這張圖把 docker-compose.yml 定義的關係畫出來：瀏覽器打 localhost:8000 進到 app 容器，app 容器透過 volume 掛載宿主機的原始碼（改程式碼不用重建映像檔），並依賴 db 容器；db 容器的資料則存進一個獨立於容器生命週期的具名 volume（db_data），容器被砍掉重建，資料庫內容不會跟著消失。

Windows 使用者的重要提醒：WSL2

如果你在 Windows 上用 Docker Desktop，強烈建議搭配 WSL2（Windows Subsystem for Linux 2）使用，而不是傳統的 Hyper-V 後端。原因是檔案系統效能：如果你的專案原始碼放在 Windows 原生檔案系統（例如 C:\projects\blog-app），再透過 volume 掛載進 Linux 容器，這種跨檔案系統的 I/O 效能會明顯拖慢——最明顯的症狀是 composer install、npm install 慢到讓人懷疑人生，或是 Laravel 的檔案變更偵測（例如開發模式下的自動重新編譯）反應遲鈍。

解法是把專案原始碼直接放在 WSL2 的 Linux 檔案系統裡（例如 \\wsl$\Ubuntu\home\你的帳號\blog-app），而不是 Windows 的 C:\ 磁碟機底下，這樣容器跟原始碼都在同一個檔案系統，I/O 效能會恢復正常。VS Code 有專門的 「WSL」擴充套件，可以直接在 WSL2 環境裡打開專案資料夾，體驗上跟本機開發沒有明顯差異。

Laravel Sail：官方包好的輕量指令

Sail 是 Laravel 官方提供的 Docker 開發環境，本質上就是「幫你寫好 Dockerfile 跟 docker-compose.yml，並包一層好記的 CLI 指令」。

安裝方式

新專案可以在建立時直接指定：

curl -s "https://laravel.build/blog-app" | bash

既有專案要加裝 Sail：

composer require laravel/sail --dev
php artisan sail:install

安裝過程會讓你勾選需要的服務（MySQL、PostgreSQL、Redis、Meilisearch 等），自動產生對應的 docker-compose.yml。

常用指令

./vendor/bin/sail up -d        # 啟動環境
./vendor/bin/sail artisan migrate   # 執行 artisan 指令
./vendor/bin/sail composer require xxx  # 執行 composer 指令
./vendor/bin/sail npm run dev  # 執行 node/npm 指令
./vendor/bin/sail test         # 執行測試
./vendor/bin/sail tinker       # 進入 Tinker 互動環境
./vendor/bin/sail mysql        # 直接連進資料庫容器的 mysql client
./vendor/bin/sail shell        # 進入 app 容器的 bash（等同 sail bash）
./vendor/bin/sail down         # 停止並移除容器（volumes 資料預設會保留）

一般會建議設一個 shell alias 讓輸入更短：

alias sail='[ -f sail ] && sh sail || sh vendor/bin/sail'

之後就能直接打 sail up -d、sail artisan migrate，體驗上跟本機直接跑 php artisan 幾乎一樣，但底層其實都在容器裡執行。

Sail 內建服務一覽

sail:install 過程中勾選的服務，會自動被寫進 docker-compose.yml。幾個常用的服務跟它們在 blog-app 裡的用途：

Mailpit 這個服務特別值得一提：開發階段測試「寄信」相關功能（例如通知信、密碼重設信）最怕的就是不小心寄到真實信箱、或想確認信件內容卻要另外裝軟體收信。Mailpit 攔截所有從你的應用程式寄出的信件，透過瀏覽器打開 http://localhost:8025 就能看到信件實際內容，這是本機開發測試信件功能時幾乎必備的工具。

搭配 Xdebug 除錯

Sail 的 Docker 映像檔已經內建 Xdebug，只是預設沒有啟用（避免拖慢一般開發時的效能）。要啟用只需要在 .env 加上：

SAIL_XDEBUG_MODE=develop,debug

然後重新 sail up -d 讓設定生效。搭配 VS Code 的 PHP Debug 擴充套件（下一節會提到），你就能在容器裡執行的 PHP 程式碼上打中斷點，逐行檢查變數狀態——這比到處插 dd() 再重新整理頁面要有效率得多，尤其是在追蹤一個「明明邏輯看起來對，但結果不對」的問題時。

該選哪一個？

• 只在 Windows 開發、不太需要跟 Linux 正式環境高度一致：Laragon 最快上手。
• 團隊協作、需要跟正式環境行為一致、之後打算用 Docker 部署：直接上 Sail，等於環境定義跟部署方式一次到位。
• 需要客製化容器內容（例如加裝少見的 PHP 擴充套件、串接特殊服務）：手寫 Dockerfile/docker-compose，Sail 產生的檔案也可以事後手動調整。

這系列後續範例不特別綁定某一種工具，你可以自由選擇你熟悉的方式跑起明天要建立的 blog-app 專案，範例指令會以 php artisan xxx 的形式呈現（如果你用 Sail，記得自行加上 sail 前綴）。

VS Code：推薦擴充套件與快捷鍵

VS Code 目前是 Laravel 開發最主流的編輯器之一，免費、跨平台、擴充套件生態成熟。推薦清單：

一份實用的 settings.json 片段

裝好擴充套件後，這裡提供一份 VS Code 專案設定（.vscode/settings.json）的起手式，讓儲存時自動排版、並避開一些 PHP 專案常見的雜訊：

{
    "editor.formatOnSave": true,
    "[php]": {
        "editor.defaultFormatter": "open-southeners.laravel-pint"
    },
    "files.exclude": {
        "**/vendor": true,
        "**/node_modules": true
    },
    "search.exclude": {
        "**/vendor": true,
        "**/node_modules": true,
        "**/storage/logs": true
    },
    "intelephense.files.exclude": [
        "**/.git/**",
        "**/vendor/**/{Tests,tests}/**"
    ]
}

把這個檔案放進專案根目錄的 .vscode/ 資料夾並提交進版本控制（Day 29 會講到 Git 版控），團隊成員只要用 VS Code 打開專案，就能自動套用同一套排版跟搜尋排除規則，不需要每個人各自設定一次。search.exclude 這幾行特別重要——沒排除 vendor/ 的話，專案內搜尋常常會被套件原始碼的搜尋結果淹沒，找不到自己寫的程式碼。

常用快捷鍵

Shift+F12（尋找所有參照）在 Laravel 專案裡特別實用——例如你想知道 PostService::listPosts() 這個方法被哪些地方呼叫，遊標放在方法名稱上按這個快捷鍵，比自己手動全域搜尋字串快得多，也不會被字串裡剛好出現同名的地方誤導。

常見錯誤與踩雷點

• Docker/Sail 的 port 被本機其他服務佔用：如果你電腦本身已經裝了 MySQL 或跑著別的網站服務，docker compose up 常會因為 port 衝突失敗。修改 docker-compose.yml 裡對應服務的對外 port（例如把 3306:3306 改成 3307:3306）即可，記得同步更新 .env 裡對應的連線 port。
• Sail 容器內外檔案權限不一致：Linux/Mac 使用者偶爾會遇到容器內建立的檔案，宿主機上顯示成 root 擁有、無法編輯，通常是 Docker Desktop 的檔案共享設定問題，重開 Docker Desktop 或調整 WWWUSER/WWWGROUP 環境變數可以解決。
• 忘記自己在用 Sail，卻直接下 php artisan：如果你的 PHP 版本或擴充套件其實是裝在容器裡，本機直接執行 php artisan 可能會因為本機沒裝對應版本而失敗，記得統一用 sail artisan。
• Windows 專案放在 C:\ 底下卻掛載進 Docker，效能異常緩慢：前面提過的 WSL2 檔案系統問題，症狀是 composer install、頁面載入都慢得不正常，把專案搬進 WSL2 的 Linux 檔案系統通常能立即改善。
• 改了 docker-compose.yml 卻沒有生效：多數設定變更（尤其是環境變數、volume 掛載）需要重新建立容器才會生效，單純 docker compose restart 不一定夠，改用 docker compose up -d --build 確保套用最新設定。
• VS Code 的 Intelephense 免費版對大型專案自動完成變慢：Intelephense 免費版有索引檔案數量的軟性限制，vendor/ 目錄龐大時可能拖慢自動完成速度，前面 intelephense.files.exclude 設定能緩解一部分，若專案真的很大，付費版的索引效能會有感提升。

小結

三種工具沒有絕對的優劣，重點是選一個跟你的團隊、部署目標一致的方案。這系列後續不會綁死某一種工具，重要的是你現在手上已經有一個能跑起來的 Laravel 13 環境，並且對 Mailpit、Xdebug 這些開發階段真正會用到的輔助工具有基本認識。

工欲善其事，必先利其器 — 《論語・衛靈公》

明日預告

Day 4 正式建立 blog-app 專案，用官方 Starter Kit 起手——你熟悉的 Breeze/Jetstream 已經換代了，新版長什麼樣子、該怎麼選，是明天的主題。