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 專業開發環境。

祝開發愉快！

羅培宸的技術筆記：從面試戰場到 AI 實戰

2026年9月9日星期三