wp-performance

WP Performance（僅後端）

使用時機

當以下情況時使用此技能：

• WordPress 網站/頁面/端點速度慢（前端 TTFB、管理後台、REST、WP-Cron）
• 需要效能分析計畫與工具建議（WP-CLI profile/doctor、Query Monitor、Xdebug/XHProf、APM）
• 正在最佳化資料庫查詢、自動載入選項、物件快取、cron 任務或遠端 HTTP 呼叫

此技能假設代理無法使用瀏覽器 UI。偏好使用 WP-CLI、日誌與 HTTP 請求。

必要輸入

• 環境與安全性：開發/測試/正式環境，任何限制（不可寫入、不可安裝外掛）。
• 如何指定安裝目標：
  • WP 根目錄 --path=<path>
  • （多站點/站點指定）--url=<url>
• 效能症狀與範圍：
  • 哪個 URL/REST 路由/管理畫面
  • 何時發生（持續發生 vs 偶發；已登入 vs 未登入）

流程

0) 防護措施：先測量，避免風險操作

1. 確認是否可以執行寫入操作（安裝外掛、修改設定、清除快取）。
2. 選擇可重現的目標（URL 或 REST 路由）並取得基準：
   • 使用 curl 測量 TTFB/時間（如可行）
   • 使用 WP-CLI 進行效能分析（如可用）

閱讀：

• references/measurement.md

1) 產生僅後端效能報告（確定性）

執行：

• node skills/wp-performance/scripts/perf_inspect.mjs --path=<path> [--url=<url>]

此指令會偵測：

• WP-CLI 可用性與核心版本
• 是否可使用 wp doctor / wp profile
• 自動載入選項大小（如可行）
• 物件快取 drop-in 是否存在

2) 快速見效：在深入分析前執行診斷

若有 WP-CLI 存取權限，優先使用：

• wp doctor check

此指令可抓出常見的正式環境問題（自動載入膨脹、SAVEQUERIES/WP_DEBUG、外掛數量、更新狀態）。

閱讀：

• references/wp-cli-doctor.md

3) 深入分析（無需瀏覽器）

建議順序：

1. wp profile stage 查看時間花費在哪個階段（bootstrap/main_query/template）。
2. wp profile hook（可選用 --url=）找出慢速的鉤子/回呼。
3. wp profile eval 針對特定程式碼路徑。

閱讀：

• references/wp-cli-profile.md

4) Query Monitor（僅後端使用）

Query Monitor 通常透過 UI 操作，但可透過 REST API 回應標頭與 _envelope 回應以無頭模式使用：

• 驗證（nonce 或應用程式密碼）。
• 請求 REST 回應並檢查標頭（x-qm-*）及/或使用 ?_envelope 時的 qm 屬性。

閱讀：

• references/query-monitor-headless.md

5) 依類別修正（選擇主要瓶頸）

根據分析輸出選擇一個主要瓶頸類別：

• 資料庫查詢 → 減少查詢次數、修正 N+1 模式、改善索引、避免昂貴的 meta 查詢。
  • references/database.md
• 自動載入選項 → 找出最大的自動載入選項，並停止自動載入大型資料。
  • references/autoload-options.md
• 物件快取未命中 → 引入快取或修正快取鍵/群組使用方式；在適當處加入持久性物件快取。
  • references/object-cache.md
• 遠端 HTTP 呼叫 → 加入逾時、快取、批次處理；避免在每次請求時呼叫遠端 API。
  • references/http-api.md
• Cron → 減少到期高峰、去重複事件、將繁重任務移出請求路徑。
  • references/cron.md

6) 驗證（重複相同測量）

• 重新執行相同的 wp profile / wp doctor / REST 請求。
• 確認效能差異且行為未改變。
• 若修正有風險，盡可能透過功能旗標或階段性部署推出。

WordPress 6.9 效能改善

分析時請注意這些 6.9 的變更：

經典主題的按需 CSS：

• 經典主題現在支援按需載入 CSS（先前僅區塊主題有此功能）。
• 僅載入頁面實際使用的區塊樣式，減少 CSS 負載 30-65%。
• 若您正在分析經典主題，此功能應已發揮作用。

無渲染阻塞資源的區塊主題：

• 未定義自訂樣式表的區塊主題（如 Twenty Twenty-Three/Four）現在可以零渲染阻塞 CSS 載入。
• 樣式來自全域樣式（theme.json）與獨立的區塊樣式，全部內嵌。
• 這大幅改善 LCP（最大內容繪製）。

內嵌 CSS 限制提高：

• 內嵌小型樣式表的閾值已提高，減少渲染阻塞資源。

參考資料：https://make.wordpress.org/core/2025/11/18/wordpress-6-9-frontend-performance-field-guide/

驗證

• 基準值與改善後的數值已記錄（相同環境、相同 URL/路由）。
• wp doctor check 結果乾淨（或改善）（如適用）。
• 日誌中無新的 PHP 錯誤或警告。
• 無需清除快取以確保正確性（清除快取應為最後手段）。

失敗模式 / 除錯

• 程式碼變更後「無變化」：
  • 您測量了不同的 URL/站點（--url 不符）、快取掩蓋了結果，或 opcode 快取過時
• 分析資料雜訊過多：
  • 排除背景任務、使用已暖機的快取測試、執行多個樣本
• SAVEQUERIES/Query Monitor 造成額外負擔：
  • 除非明確核准，否則不要在正式環境執行

升級處理

• 若為正式環境且無明確核准，請勿：
  • 安裝外掛、啟用 SAVEQUERIES、執行負載測試，或在流量期間清除快取
• 若需要系統層級分析（APM、PHP 分析器擴充功能），請與維運/主機團隊協調。