一句話破題

框架本身只是起點，真正讓專案完整的往往是周邊的生態系工具。今天把 blog-app 之後最可能用到的幾個第一方套件盤點一遍——Telescope、Sanctum、Octane、Socialite、Laravel Boost——順便從 Composer 的套件衝突處理講起。

Composer 套件管理：避免衝突的基本功

管理套件最典型的問題有兩種：

版本相依衝突：兩個套件都依賴同一個底層套件（例如都依賴 guzzlehttp/guzzle），但要求的版本範圍對不上，Composer 會直接拒絕安裝並列出衝突原因。解法通常是找兩者都能接受的版本區間，或等其中一個套件釋出相容新版。

功能重疊衝突：Day 4 提過的例子——Laravel 12 起官方推出新版 Starter Kit，跟 Breeze/Jetstream 這類舊版第三方套件如果同時安裝，容易在路由、認證邏輯上互相打架。這也是為什麼官方文件現在已經移除了 Breeze/Jetstream 的介紹頁面，把「不要混用多套認證方案」這件事講清楚。

常用指令複習：

composer require vendor/package         # 安裝
composer require vendor/package --dev   # 只在開發環境需要
composer update vendor/package          # 更新單一套件（避免無差別 update 所有套件）
composer remove vendor/package          # 移除
composer outdated                       # 列出有新版可更新的套件

排查版本衝突的實用指令

遇到 Composer 拒絕安裝、噴出一長串版本衝突訊息時，與其憑感覺猜測，用這個指令直接問清楚：

composer why-not laravel/framework 13.0

why-not 會列出目前哪些已安裝的套件會阻止你升級到指定版本，直接告訴你問題出在哪個相依套件，比自己一行一行讀衝突訊息快得多。反過來，如果你想知道「為什麼某個套件被安裝了」（例如懷疑是不是被誰間接帶進來的相依），用 composer why：

composer why guzzlehttp/guzzle   # 列出哪些套件依賴了 guzzlehttp/guzzle

composer.lock：鎖定確切版本，確保團隊環境一致

composer.json 定義的是版本範圍（Day 2 講過的 ^13.0 這類語法），composer.lock 記錄的則是這次安裝實際解析出來的確切版本號。這個檔案必須提交進版本控制——它確保團隊每個成員、以及 CI/部署環境，用 composer install（而非 composer update）安裝時，拿到的是完全相同的套件版本組合，不會因為「我裝的時候套件剛好出了新版」而導致環境不一致。這是新手容易忽略、卻很基本的一條規則：composer.lock 一定要進版控，.env 一定不要，兩者的處理原則正好相反。

Telescope：本機開發的除錯儀表板

composer require laravel/telescope --dev
php artisan telescope:install
php artisan migrate

安裝後可以在 /telescope 看到請求記錄、資料庫查詢（含執行時間，抓 N+1 問題很好用）、Job 執行狀況、Log、Exception 等即時儀表板。config/telescope.php 可以設定要不要在正式環境啟用（多數專案只在本機/測試環境開啟，正式環境用 Telescope 需要額外考慮效能開銷與存取權限控管）。

常用的客製化設定

Telescope 記錄的資料會持續累積，config/telescope.php 有幾個實務上常調整的選項：

'watchers' => [
    Watchers\QueryWatcher::class => [
        'enabled' => env('TELESCOPE_QUERY_WATCHER', true),
        'slow' => 100,   // 只記錄執行時間超過 100 毫秒的查詢，避免記錄量爆炸
    ],
],

搭配定期清理舊紀錄（避免 telescope_entries 資料表無限增長）：

php artisan telescope:prune --hours=48   # 清除 48 小時前的紀錄，適合排進 Day 25 的排程任務

slow 這個閾值特別實用——開發階段你通常只關心「有沒有異常慢的查詢」，而不是每一次幾毫秒的正常查詢都要記錄，適度調高閾值能讓 Telescope 的資料量維持在可管理的範圍。

Sanctum：API Token 與 SPA 認證

這裡有個常見的過時認知：「Sanctum 是新專案預設附帶的」——這個說法現在已經不成立。Day 4 講過，新版 Starter Kit 的認證基礎是 Fortify，Sanctum 需要另外安裝：

php artisan install:api   # Day 14 已經用過，這個指令會順便裝好 Sanctum

Sanctum 解決兩種常見情境：

• API Token 認證：行動裝置 App、第三方系統呼叫你的 API，用 $user->createToken('mobile-app')->plainTextToken 產生的 Token 認證。
• SPA 認證：如果 blog-app 之後改用 React/Vue Starter Kit（Day 4 提過的另一個選項），前端 SPA 透過 Session-based 認證（而不是 Token）跟同源的 Laravel API 溝通，Sanctum 提供對應的中介層處理這種情境。

Token 權限範圍（Abilities）與撤銷

Token 認證除了「有沒有登入」，Sanctum 還支援更細緻的權限控制，讓不同用途的 Token 只能做特定的事：

// 只允許讀取，不允許寫入的 Token（例如給唯讀報表工具用）
$token = $user->createToken('readonly-tool', ['posts:read'])->plainTextToken;

// Controller 裡檢查目前請求用的 Token 是否具備特定能力
if ($request->user()->tokenCan('posts:read')) {
    // ...
}

// 撤銷特定 Token
$user->tokens()->where('name', 'mobile-app')->delete();

// 撤銷使用者所有 Token（例如「登出所有裝置」功能）
$user->tokens()->delete();

abilities（權限範圍）機制在 blog-app 未來如果要開放給第三方開發者串接 API 時特別重要——你可以核發一個「只能讀取公開文章、不能建立/刪除」的受限 Token，即使這個 Token 外洩，造成的損害也被限制在唯讀範圍內，這是 API Token 設計上很基本但容易被忽略的最小權限原則。

Octane：把 PHP 應用變成常駐服務

一般 PHP-FPM 架構下，每個請求都要重新啟動框架（bootstrap 整個應用程式一次），Octane 透過 FrankenPHP、Swoole、RoadRunner 這類高效能應用伺服器，讓應用程式常駐在記憶體裡，省去每次請求重複啟動的開銷：

composer require laravel/octane
php artisan octane:install
php artisan octane:start

Windows 支援現況：Octane 在 Windows 上一直是「無法直接使用」，實務上仍然建議透過 WSL2 或 Docker（原生支援尚不完整）。不過 Octane 支援的伺服器選項之一 FrankenPHP 現在已經提供獨立的 Windows 執行檔，如果你想在原生 Windows 環境嘗試，可以留意這個選項的後續發展。

常駐架構也帶來一個常見的坑：應用程式狀態如果沒有正確重置，可能會「洩漏」到下一個請求（例如某個 Service 類別把資料存進自己的屬性、又被 singleton() 綁定，常駐模式下這個屬性值會跨請求殘留）。Day 23 提過的 scoped() 綁定，正是為了在 Octane 這類長駐環境裡，讓某些綁定在每個請求週期正確重置而存在。

Octane 的併發任務

除了效能提升，Octane 還提供一個一般 PHP-FPM 架構不容易做到的能力——同一個請求內並發執行多個獨立任務：

[$posts, $stats] = Octane::concurrently([
    fn () => Post::with('author')->latest()->paginate(10),
    fn () => Post::whereNotNull('published_at')->count(),
]);

這在需要「同一個頁面同時準備好幾份互不相依的資料」時，能比依序執行更快回應，是 Octane 生態圈裡除了「省去重複啟動開銷」之外，另一個值得認識的進階能力。

Socialite：第三方社群登入

composer require laravel/socialite

// 導向到 Google 登入頁面
return Socialite::driver('google')->redirect();

// Google 導回後取得使用者資料
$googleUser = Socialite::driver('google')->user();
$user = User::updateOrCreate(
    ['email' => $googleUser->getEmail()],
    ['name' => $googleUser->getName()],
);

Day 4 提過 Socialite 跟 WorkOS AuthKit 的定位差異：Socialite 適合「加個社群登入按鈕」的單純情境，WorkOS AuthKit 適合需要企業 SSO、Passkey 的情境。blog-app 如果只是想讓讀者用 Google 帳號快速註冊，Socialite 是更輕量的選擇；如果 blog-app 未來要做成給多個團隊使用的 SaaS 服務、需要企業級單一登入，Day 4 的 WorkOS AuthKit 變體更合適。兩者不互斥，可以視功能需求並存。

Laravel Boost：AI 輔助開發工具

2025 年才發布的新套件，也是這系列最貼近「生態系最新動態」的主題。Boost 的定位是「AI coding starter kit for Laravel」——不是取代開發者，而是讓你的 AI 編碼助手（Claude Code、Cursor 等）更懂你的 Laravel 專案。

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

核心能力：

• Laravel 專屬 MCP Server：提供給 AI agent 一組工具，能讀取專案的資料庫 schema、查詢資料、執行 Tinker 程式碼片段、讀取最近的錯誤日誌、列出路由等，讓 AI 不只是「憑空生成程式碼」，而是能主動查詢你專案的實際狀態。
• 版本專屬文件查詢：Boost 蒐集了 Laravel 生態系（含常見套件如 Inertia、Livewire）的版本對應文件並向量化，AI 可以在「你專案實際使用的版本」這個上下文下查詢正確的 API 用法，減少版本錯配的幻覺。
• AI 開發指南：內建針對 Laravel 專案的指導規則（何時該寫測試、遵守哪種程式風格），這些規則本身也是版本化、可調整的。

Laravel 13 起，Boost 有了一個特別的新用途：官方升級指南直接建議透過 Boost 自動化升級流程——只要在 Laravel 12 專案裡先裝好 Boost ^2.0，接著在 Claude Code、Cursor、Gemini、VS Code 等工具裡下 /upgrade-laravel-v13 指令，就能取得引導式的升級提示，這也是這系列 Day 1 提到「我全程搭配 AI 協作完成這次更新」背後所呼應的同一個技術趨勢——Laravel 官方本身也在往「框架 + AI 助手協作」的方向前進。

其他值得認識的第一方套件

除了上面深入介紹的幾個，還有幾個 Laravel 官方維護的套件，blog-app 目前用不到，但值得知道存在，未來有對應需求時能想起來查：

Sanctum 跟 Passport 容易被搞混：Sanctum 適合「自己的 App/SPA」這種相對單純的認證需求，Passport 適合真正的 OAuth2 場景（例如「讓第三方應用程式申請一組 API Key，代表使用者存取部分資料，使用者能個別撤銷授權」這種更複雜的授權流程）。多數專案（包括 blog-app）用 Sanctum 就足夠，Passport 除非有明確的 OAuth2 需求，否則不建議直接跳過去用，複雜度不成比例。

常見錯誤與踩雷點

• 正式環境忘記關閉或限制 Telescope 存取：Telescope 記錄的內容包含請求細節、資料庫查詢，可能含敏感資訊，正式環境如果要開啟，務必透過 config/telescope.php 的 Gate 限制只有特定使用者能存取。
• 在 Octane 常駐環境裡把「請求層級」的狀態綁成 singleton()：常駐架構下 singleton() 綁定的實例會跨請求存活，如果裡面存了跟單次請求相關的狀態，會造成資料錯亂，需要的話改用 scoped()。
• 同時裝了 Socialite 又裝 WorkOS AuthKit 卻沒想清楚分工：兩者都能處理「登入」，同時存在但沒有明確界定各自負責的場景，容易讓認證邏輯變得混亂，建議一開始就明確決定「一般讀者用哪套、企業客戶用哪套」。
• composer.lock 沒有提交進版本控制：導致團隊成員或部署環境安裝到不一致的套件版本組合，這是很基本但容易被忽略的規則。
• 核發 API Token 沒有限制 abilities，一律給完整權限：即使目前用不到細緻的權限控制，養成「依實際用途限制 Token 能力範圍」的習慣，能大幅降低 Token 外洩時的實際損害。

小結

今天把 blog-app 生態系周邊最實用的幾個套件盤點一遍：Telescope 除錯（含資料清理與慢查詢閾值設定）、Sanctum 處理 API/SPA 認證（含 Token 權限範圍與撤銷機制）、Octane 提升效能（含併發任務能力）、Socialite 處理社群登入、Laravel Boost 這個框架與 AI 協作的最新指標性套件，也簡短認識了 Cashier/Pennant/Scout/Passport 這幾個未來可能用到的官方套件，以及 composer.lock 這條容易被忽略的版控規則。

尺有所短，寸有所長 — 《楚辭・卜居》

明日預告

Day 29 是這系列最長的實戰演練：從零打造一個 LINE Bot + OpenAI 聊天機器人，接著走一次 Git 版控流程，最後部署上線到 Render。