全端開發新標準：Laravel 12 + Vue 3 + Pinia + Tailwind CSS v4 容器化實戰

前言

隨著 Laravel 12 的發佈，後端開發的穩定性與前端生態的結合達到了新的高度。在現代全端開發中，我們追求的不僅是功能實現，更是開發體驗（DX）與部署的標準化。本文將展示如何整合 Vue 3、Pinia 狀態管理、以及最新發佈的 Tailwind CSS v4，並透過 Docker 實現一鍵式環境啟動。

---

1. 現代化全端架構概覽

• Laravel 12：提供強大的 Eloquent ORM 與穩定可靠的 API 路由。

• Vue 3 (Composition API)：靈活的前端組件化開發。

• Pinia：輕量化、符合直覺的 Vue 狀態管理工具，取代 Vuex。

• Tailwind CSS v4：全新的引擎，更快的編譯速度與更簡潔的配置。

• Vite：極速的前端構建工具，支援 HMR（熱模組替換）。

• Docker：消除「在我的電腦上可以跑」的環境差異問題。

---

2. 專案目錄結構

一個清晰的結構有助於團隊協作：

Plaintext

laravel-vue-docker/
├── docker-compose.yml     # 多容器編排
├── Dockerfile             # PHP-FPM 鏡像定義
├── nginx/
│   └── default.conf       # Nginx 反向代理配置
├── resources/
│   ├── js/
│   │   ├── app.js         # 入口文件
│   │   ├── stores/        # Pinia 狀態管理
│   │   └── components/    # Vue 組件
│   └── css/
│       └── app.css        # Tailwind 指令
└── .env                   # 環境變數

---

3. Docker 化環境建置

Dockerfile

我們將 PHP 與 Node.js 環境整合，方便在構建階段直接完成前端編譯。

Dockerfile

FROM php:8.2-fpm

# 安裝系統依賴與 PHP 擴展
RUN apt-get update && apt-get install -y \
    git unzip libzip-dev nodejs npm && \
    docker-php-ext-install pdo_mysql zip

# 引入 Composer
COPY --from=composer:2 /usr/bin/composer /usr/bin/composer

WORKDIR /var/www/html
COPY . .

# 權限修正（Laravel 運作關鍵）
RUN chown -R www-data:www-data storage bootstrap/cache

# 安裝依賴並編譯前端資產
RUN npm install && npm run build

EXPOSE 9000
CMD ["php-fpm"]

docker-compose.yml

定義服務鏈結，確保 app 容器能與 mysql 正確通訊。

YAML

version: "3.9"
services:
  app:
    build: .
    container_name: laravel-app
    volumes:
      - .:/var/www/html
    depends_on:
      - mysql

  nginx:
    image: nginx:alpine
    container_name: laravel-nginx
    ports:
      - "80:80"
    volumes:
      - .:/var/www/html
      - ./nginx/default.conf:/etc/nginx/conf.d/default.conf
    depends_on:
      - app

  mysql:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: rootpass
      MYSQL_DATABASE: laravel
    volumes:
      - mysql_data:/var/lib/mysql

volumes:
  mysql_data:

---

4. 前端整合：Vue 3 + Pinia + Tailwind v4

安裝與配置

在 Laravel 12 中安裝前端套件：

Bash

npm install vue@3 pinia
npm install -D tailwindcss @tailwindcss/vite

(註：Tailwind v4 在 Vite 中現在多透過插件形式導入，配置更加自動化)

Pinia Store (resources/js/stores/counter.js)

利用 Pinia 處理全域狀態：

JavaScript

import { defineStore } from 'pinia'

export const useCounterStore = defineStore('counter', {
  state: () => ({ count: 0 }),
  actions: {
    increment() {
      this.count++
    }
  }
})

Vue 組件 (resources/js/components/Counter.vue)

使用 Tailwind v4 進行樣式設計：

程式碼片段

<template>
  <div class="p-6 bg-slate-100 rounded-xl shadow-md max-w-sm mx-auto">
    <h1 class="text-3xl font-extrabold text-indigo-600">計數器: {{ counter.count }}</h1>
    <button 
      @click="counter.increment" 
      class="mt-4 px-6 py-2 bg-indigo-500 text-white rounded-full hover:bg-indigo-700 transition"
    >
      增加數值
    </button>
  </div>
</template>

<script setup>
import { useCounterStore } from '../stores/counter'
const counter = useCounterStore()
</script>

---

5. Nginx 與 Vite 的配合

在 nginx/default.conf 中，確保 PHP 請求正確轉發至 app 容器：

Nginx

location ~ \.php$ {
    fastcgi_pass app:9000;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    include fastcgi_params;
}

---

6. 常見問題排錯 (Troubleshooting)

問題	解決方案
樣式未生效	檢查 resources/css/app.css 是否包含 @theme 或 Tailwind 指令。
Vite 資源加載失敗	確認 Blade 模板中使用 @vite(['resources/js/app.js'])。
資料庫連線拒絕	檢查 .env 中的 DB_HOST 必須對應 Docker 的服務名稱：mysql。
權限報錯	執行 docker exec -it laravel-app chmod -R 775 storage。

---

7. 結語

這套 Laravel 12 + Vue 3 + Pinia + Tailwind v4 的組合代表了當前開發的高效能典範。透過 Docker 封裝，我們不僅獲得了極速的開發反饋，更讓系統在從開發到生產的轉換過程中，保持了極高的穩定性。