WSL2 + Laragon：打造極速 Laravel 專業開發環境完整教學
核心架構
Windows 負責入口與網域解析（Laragon Nginx 反向代理 +*.test），
WSL2 負責真正的 Linux 執行環境與極速檔案 I/O。
這是目前 Windows 上 Laravel 開發在「效能 × 便利性」之間最平衡的實戰方案之一。
架構總覽
[ Windows 側：入口與輔助工具 ]
├── Laragon (Nginx) → 自動網域解析 (*.test) + 反向代理 (Port 80/443)
├── 瀏覽器 / VS Code / GUI 資料庫工具 (TablePlus、DBeaver、HeidiSQL 等)
└── Hosts 檔案管理
│ 流量轉發 (proxy_pass http://127.0.0.1:8000)
▼
[ WSL2 側：真正的 Linux 開發環境 ]
├── Linux 原生檔案系統 (/home/username/projects/...) → 極速 I/O（關鍵！）
├── PHP-CLI / Composer / Node.js (NVM)
├── php artisan serve (Port 8000) 或 Nginx + PHP-FPM
└── MySQL / Redis / Mailpit 等原生服務
效能關鍵警告
專案必須放在 WSL2 的 Linux 原生目錄（/home/...），絕對禁止放在 /mnt/c/...。
跨檔案系統（9P）會讓 Composer、npm、測試執行速度暴跌 5～10 倍以上。
第一步：配置 WSL2（Ubuntu）核心環境
1. 安裝 / 更新 WSL2
以系統管理員身分開啟 PowerShell 或 Windows Terminal：
wsl --install
# 若已安裝，更新至最新版本
wsl --update
wsl --set-default-version 2
安裝完成後重開機，並設定預設發行版（建議 Ubuntu 22.04 或 24.04）。
2. 安裝 PHP 與開發工具鏈
開啟 WSL2 Ubuntu 終端機，執行：
sudo apt update && sudo apt upgrade -y
# 加入 Ondřej Surý 的 PHP PPA（取得最新穩定版）
sudo apt install -y software-properties-common
sudo add-apt-repository ppa:ondrej/php -y
sudo apt update
# 安裝 PHP 8.3 核心 + Laravel 常用擴充（可依需求改為 8.4）
sudo apt install -y \
php8.3-cli php8.3-fpm php8.3-curl php8.3-xml php8.3-mbstring \
php8.3-mysql php8.3-sqlite3 php8.3-zip php8.3-gd php8.3-bcmath \
php8.3-intl php8.3-redis php8.3-soap php8.3-imagick \
unzip curl git vim
# 安裝 Composer
curl -sS https://getcomposer.org/installer | php
sudo mv composer.phar /usr/local/bin/composer
composer self-update
# 安裝 NVM + Node.js LTS（Vite 與前端編譯必備）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.bashrc
nvm install --lts
nvm use --lts
node -v && npm -v
3. 安裝 MySQL 與 Redis
sudo apt install -y mysql-server redis-server
# 啟動服務
sudo service mysql start
sudo service redis-server start
# 設定 MySQL root 密碼與安全選項（建議執行）
sudo mysql_secure_installation
建立開發用資料庫使用者（範例）：
sudo mysql -e "
CREATE DATABASE laravel_dev CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'laravel'@'%' IDENTIFIED BY 'secret';
GRANT ALL PRIVILEGES ON laravel_dev.* TO 'laravel'@'%';
FLUSH PRIVILEGES;
"
第二步：建立 Laravel 專案（嚴格遵守目錄規則）
# 切換至家目錄並建立專案資料夾
cd ~
mkdir -p projects && cd projects
# 建立全新 Laravel 專案
composer create-project laravel/laravel my-app
cd my-app
# 設定 .env（範例）
cp .env.example .env
php artisan key:generate
# 編輯 .env
# DB_CONNECTION=mysql
# DB_HOST=127.0.0.1
# DB_PORT=3306
# DB_DATABASE=laravel_dev
# DB_USERNAME=laravel
# DB_PASSWORD=secret
# 執行遷移
php artisan migrate
# 啟動開發伺服器（測試用）
php artisan serve --host=0.0.0.0 --port=8000
此時在 WSL 內部可透過 http://127.0.0.1:8000 存取。
第三步：設定 Laragon 作為 Windows 反向代理
1. 建立 Nginx 虛擬主機設定
開啟資料夾：C:\laragon\etc\nginx\sites-enabled\
新建檔案 my-app.test.conf（不要加 auto. 前綴，否則會被 Laragon 覆蓋）：
server {
listen 80;
server_name my-app.test;
# 若要支援 HTTPS，可再加 listen 443 ssl; 並設定憑證
location / {
proxy_pass http://127.0.0.1:8000;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
# 支援 Vite HMR（熱模組替換）
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
}
}
2. 更新 Hosts 檔案
在 Laragon 介面點擊 Reload，或手動編輯C:\Windows\System32\drivers\etc\hosts（需系統管理員權限）：
127.0.0.1 my-app.test
現在只要 WSL 內的 php artisan serve 正在執行，瀏覽器輸入
http://my-app.test 即可直接連通。
3. Vite 熱更新額外設定（建議）
編輯 vite.config.js：
import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';
export default defineConfig({
plugins: [
laravel({
input: ['resources/css/app.css', 'resources/js/app.js'],
refresh: true,
}),
],
server: {
host: '0.0.0.0',
hmr: {
host: 'my-app.test',
},
},
});
第四步：自動化整合（Laragon Procfile）
開啟 C:\laragon\usr\Procfile，加入以下內容：
# 自動啟動 WSL 內的服務
WSL_MySQL: autorun wsl -d Ubuntu -u root -- service mysql start
WSL_Redis: autorun wsl -d Ubuntu -u root -- service redis-server start
# 自動啟動 Laravel 開發伺服器（請依實際發行版名稱與路徑調整）
WSL_App: autorun wsl -d Ubuntu -- bash -c "cd ~/projects/my-app && php artisan serve --host=0.0.0.0 --port=8000"
之後只需點擊 Laragon 的 Start All，背景就會自動完成所有啟動程序。
提示：可依專案新增多個
WSL_App_XXX條目，或改用腳本統一管理。
第五步：VS Code 完美整合
- 在 Windows 端安裝擴充套件：WSL（Microsoft 官方）。
- 在 WSL 終端機進入專案目錄後執行：
cd ~/projects/my-app
code .
VS Code 會自動切換為 WSL: Ubuntu 遠端模式。
所有終端機、Git、PHP IntelliSense、Xdebug、測試執行皆在 Linux 原生環境運行，體驗極致流暢。
推薦額外安裝的擴充：
- PHP Intelephense
- Laravel Extra Intellisense
- Laravel Blade Snippets
- Tailwind CSS IntelliSense（若使用）
- GitLens
進階加強建議
1. 改用 Nginx + PHP-FPM（效能更好）
artisan serve 是單執行緒，適合輕量開發。若需要更高並發，可在 WSL 內安裝 Nginx + PHP-FPM，再讓 Laragon 只做反向代理或直接使用 WSL 的 Nginx。
2. 加入 Queue、Scheduler、Mailpit
可在 Procfile 中繼續擴充，或使用 php artisan dev（Laravel 較新版本）一次啟動多個程序。
3. HTTPS 支援
Laragon 提供 Auto SSL，可為 my-app.test 產生本地憑證，再於 Nginx conf 中啟用 443。
4. 多專案管理
每個專案各自一個 .conf 與 Procfile 條目，或撰寫簡單的 bash 腳本統一啟動/停止。
5. 資料庫 GUI 工具連線
- Host：
127.0.0.1 - Port：
3306 - 使用者 / 密碼：依你在 WSL 建立的帳號
若連線失敗，檢查 MySQL 的 bind-address 是否允許。
常見問題排除
| 問題 | 可能原因與解決方式 |
|---|---|
my-app.test 無法連線 | 確認 artisan serve 有在跑、Nginx conf 正確、Hosts 已更新、Laragon 已 Reload |
| Vite HMR 失效 | 檢查 proxy Upgrade header 與 vite.config.js 的 host 設定 |
| Composer / npm 極慢 | 專案是否放在 /mnt/c？立刻移回 /home |
| MySQL 連線被拒 | 服務是否啟動？密碼是否正確？防火牆？ |
| Procfile 沒生效 | 確認使用 autorun、發行版名稱正確（wsl -l -v 查看） |
總結
這套「Windows 入口 + WSL2 核心」架構結合了：
- Laragon 的便利網域與 GUI
- WSL2 原生 Linux 的極致檔案 I/O 與工具鏈
- VS Code 無縫遠端開發體驗
完成上述設定後，你將擁有一個快速、穩定、可擴充的 Laravel 專業開發環境。
祝開發愉快！
