月份: 2025 年 4 月

Composer\Config::disableProcessTimeout
npx concurrently -c "#93c5fd,#c4b5fd,#fb7185,#fdba74" "php artisan serve" "php artisan queue:listen --tries=1" "php artisan pail --timeout=0" "npm run dev" --names=server,queue,logs,vite
'npx' is not recognized as an internal or external command,
operable program or batch file.
Script npx concurrently -c "#93c5fd,#c4b5fd,#fb7185,#fdba74" "php artisan serve" "php artisan queue:listen --tries=1" "php artisan pail --timeout=0" "npm run dev" --names=server,queue,logs,vite handling the dev event returned with error code 1

1. 確認是否安裝 Node.js

打開命令提示字元（CMD）或 PowerShell，輸入：

node -v
npm -v
npx -v

• 如果出現錯誤表示沒安裝。
• 如果 node、npm 有版本，但 npx 沒有，表示環境變數可能有問題。

2. 安裝 Node.js（如果尚未安裝）

請到官方網站下載安裝程式：

🔗 Node.js 官方網站

• 選擇 LTS 版本安裝即可（例如：v20.x LTS）
• 勾選安裝選項時，確保選擇了 “Add to PATH”

3. 安裝完後重啟終端機（或重新登入）

然後重新輸入：

npx -v

如果正常出現版本號，就表示你可以繼續使用：

composer run dev

小提醒：你這段 composer.json 裡的 scripts 是這樣的：

"scripts": {
  "dev": "npx concurrently ...",
}

如果你還沒安裝 concurrently，也可能會出錯，這時候可以執行：

npm install concurrently --save-dev

依據 Laravel 12 官方文件 以及 Livewire 3 快速入門文件 調整後的開發標準指南，此文件旨在統一團隊在 Laravel 應用程式（含 Livewire 3 元件）上的開發風格與最佳實踐。文件中的各項規範可根據專案需求進行進一步調整與擴充。

1. 總則

• 目標：
  • 統一程式碼撰寫風格，增進專案可讀性與維護性
  • 遵從 Laravel 12 與 Livewire 3 官方文件中的最佳實踐與建議
  • 提高團隊協作效率，降低因風格不一致而產生的錯誤與溝通成本
• 參考文件：
  • Laravel 12.x 官方文件
  • Livewire 3 快速入門文件

2. 基本程式碼風格

2.1. 格式規範

• PSR-12 與 Laravel 官方建議：
  • 每個 PHP 檔案以 <?php 開頭，無閉合標籤
  • 採用 4 個空白進行縮排，避免使用 Tab
  • 每行結尾不得有多餘空白，並維持統一行寬風格
• 引號使用：
  • 根據是否需要變數解析來選擇單引號與雙引號，建議全專案內風格保持一致
• 括號與空白：
  • 控制結構（if、foreach、while 等）應符合 PHP 與 Laravel 標準，例如控制結構與括號之間保持單一空白
  • 函式與方法定義、呼叫時內部參數列表應避免多餘空格

2.2. 文件與注釋

• DocBlock 標註：
  • 每個類別、方法、屬性均建議撰寫 PHPDoc，明確標示參數、返回型別與可能的例外狀況
  • 針對複雜邏輯區塊，可加入區塊式注釋以提升可讀性

3. 命名慣例與目錄結構

3.1. 檔案與目錄命名

• 目錄結構：
  • Laravel 核心程式碼放置在 app/ 目錄下，Livewire 相關元件則統一放置在 app/Http/Livewire
  • Blade 模板建議依照功能分類置於 resources/views 下，例如 resources/views/livewire
• 檔案與類別命名：
  • 類別名稱採用 PascalCase（例如：UserController、OrderService、UserProfile）
  • Blade 模板檔案名稱採小寫加連字符分隔（例如：user-profile.blade.php）
  • 文件名稱與內容需對應，避免命名不一致

3.2. 命名細則

• 方法與屬性：
  • 採用 camelCase（例如：getUserData()、orderId）
• 常數：
  • 全部大寫，使用底線連接，例如：STATUS_ACTIVE

4. 控制器、服務與商業邏輯

4.1. 控制器實作

• 精簡與職責單一：
  • 控制器應專注於請求處理與回傳結果，將複雜商業邏輯拆出放入 Service 或 Action 類別中
  • 採用依賴注入（Dependency Injection）以便於單元測試與維護
• RESTful 與資源路由：
  • 儘量使用 Laravel 提供的 resource controllers 來管理 CRUD 操作
  • 使用路由群組與中介層（Middleware）統一管理權限驗證與請求前置處理

4.2. 表單驗證

• Laravel Form Request 與 Livewire 驗證：
  • 對於複雜驗證邏輯，建議使用 Form Request 類別將驗證規則抽離至控制器之外
  • 在 Livewire 元件中，則可定義 $rules 屬性和利用 $this->validate() 或 $this->validateOnly() 驗證更新的欄位
  • 請參考 Laravel 表單驗證 與 Livewire 驗證指南

5. Blade 模板與前端資源

5.1. Blade 模板

• 模板繼承與組件化：
  • 推薦使用 Blade 模板繼承機制（例如：layouts/app.blade.php）統一全站前端佈局
  • 利用 Blade Components 與 Slots 重用共用視圖片段，確保視圖邏輯簡單明瞭
  • 請參考 Laravel Blade 模板

5.2. Livewire 與前端整合

• Livewire 標籤與資源：
  • 在主版面（layout）中引入 Livewire 必要的樣式與腳本：使用 @livewireStyles 與 @livewireScripts 指令
  • 於 Blade 中引入 Livewire 元件時，建議採用 <livewire:component-name /> 或 @livewire('component-name') 語法
• 資料綁定與事件：
  • 儘量運用 Livewire 提供的雙向資料綁定（例如 wire:model、wire:model.defer）與事件（例如 wire:click、wire:submit）
  • 如需更複雜的前端互動，可搭配 Alpine.js（官方文件中亦有推薦做法）

6. Livewire 3 專屬標準

6.1. 元件結構與定義

• 基本架構：
  • 每個 Livewire 元件應繼承自 Livewire\Component，並儘量使用 PHP 8 的屬性型別提示以提升程式明確性
  • 建議所有元件公開狀態僅限必須供前端綁定的屬性
• 驗證與資料更新：
  • 在元件內定義驗證規則（例如：protected array $rules = []），並根據需要在 updated() 或具名更新方法中觸發局部驗證
  • Livewire 3 延續了自動執行元件生命週期（lifecycle hooks）與精簡狀態管理的優點，請參照 Livewire 3 快速入門 取得最新建議

Livewire 3 元件範例：

<?php

namespace App\Http\Livewire;

use Livewire\Component;

class UserProfile extends Component
{
    public string $name = '';
    public string $email = '';

    protected array $rules = [
        'name'  => 'required|string|min:3',
        'email' => 'required|email'
    ];

    // 當單一屬性更新時僅驗證該屬性，Livewire 3 建議使用具名事件（例如：updatedName）
    public function updatedName(): void
    {
        $this->validateOnly('name');
    }

    public function updateProfile(): void
    {
        $validatedData = $this->validate();
        // 執行後端更新邏輯，例如儲存至資料庫
    }

    public function render()
    {
        return view('livewire.user-profile');
    }
}

6.2. 元件溝通與事件處理

• 事件發布與監聽：
  • 採用 Livewire 內建事件系統，在元件或元件與父母件之間傳遞必要事件
  • 命名規則需具意義，例如 userUpdated，確保其他團隊成員能迅速理解其用途
• 元件拆分：
  • 若單個元件功能過於複雜，應進行拆分為多個專注於單一責任的子元件，以便維護與重用

7. 測試與品質保證

7.1. 單元測試與功能測試

• 測試策略：
  • 使用 tests/Feature 與 tests/Unit 目錄分別存放功能與單元測試
  • Livewire 元件建議利用官方提供的測試工具進行整合與單元測試，確保前端與後端行為一致
• 自動化測試整合：
  • 建議將測試納入 CI/CD 流程，定期執行測試以確保程式碼品質

7.2. 靜態分析

• 程式碼檢查工具：
  • 使用 PHP CS Fixer、PHPStan、Psalm 等工具作為開發流程的一部分，確保程式碼符合規範與沒有潛在錯誤

8. 安全性、部屬與環境設定

8.1. 安全性

• 資料輸出與防禦：
  • 在 Blade 中預設轉譯所有輸出（使用 {{ }}），對於需要非轉譯的情形使用 {!! !!} 並謹慎處理
  • 採用 Laravel 內建的 CSRF 保護機制，確保所有表單使用 @csrf
• 權限管理：
  • 結合 Laravel Gate 與 Policy 機制進行權限驗證，避免在控制器中寫入過多授權邏輯

8.2. 部屬與環境設定

• 環境管理：
  • 使用 .env 檔區分開發、測試與生產環境，並妥善保護敏感資訊
  • 定期更新依賴以確保安全性與相容性

9. 版本控管與團隊協作

• Git 分支策略：
  • 採用 Git Flow 或類似流程，清楚區分 feature、bugfix 與 release 分支
  • 提交訊息需具描述性與意義，讓團隊成員能快速理解變更內容
• Code Review 與文件維護：
  • 定期進行程式碼審查（Code Review），並確保團隊一致遵守上述規範
  • 持續更新技術文件與內部 Wiki，以反映最新的開發趨勢與實踐