wp-playground

wp-playground 技能概覽

wp-playground 是用來建立並操作 WordPress Playground 執行個體的技能，當你需要的是可丟棄、可重現的環境，而不是完整的本機 WordPress stack 時，它特別好用。wp-playground 技能最適合外掛與佈景主題開發者、QA 測試人員，以及想要重現問題、測試版本，或分享可在瀏覽器中、或透過 @wp-playground/cli 執行的設定的後端開發者。

最重要的是它解決的工作：快速把 WordPress 網站跑起來，掛載正確的程式碼，選好對應的 WP/PHP 版本，並保留足夠的控制權來除錯或封裝結果。它不是一個泛用的「幫我寫 WordPress 提示詞」技能；它比較像一份實用的 wp-playground guide，用來處理受控環境、blueprint、snapshot 與隔離測試。

適合可丟棄的 WordPress 工作流程

在以下情境使用 wp-playground：

• 需要快速開一個暫時性的 WordPress 網站來驗證外掛或佈景主題變更，
• 需要針對特定的 WordPress 或 PHP 版本測試，
• 需要執行 blueprint 或產生 snapshot 以便分享，
• 需要在不影響正式環境或本機資料庫的情況下，於隔離狀態下除錯行為。

它和其他方案有什麼不同

最大的差異在於 CLI 工作流程、blueprint 支援，以及可預期的短暫執行時環境。當你重視可重現性勝過精美介面時，wp-playground 很合適。另一個關鍵點是這個環境以 SQLite 為後端，並且基於 WebAssembly，這會讓它在效能與限制上，和傳統伺服器安裝方式有所不同。

先了解的重要限制

只有在你能接受可丟棄環境的前提下，這才是合適的選擇。它不適合正式資料、長期保留的本機狀態，或需要傳統 MySQL-based WordPress stack 的工作流程。為了達到最佳效果，應把它視為受控測試場，而不是主要開發環境的替代品。

如何使用 wp-playground 技能

安裝並開啟來源檔案

先依照你目錄工具的標準 wp-playground install 路徑開始，接著在請它做事之前先閱讀這個技能的來源檔。這個 repo 的關鍵檔案是 SKILL.md、references/blueprints.md、references/cli-commands.md 和 references/debugging.md。這些檔案會告訴你技能預期接收哪些輸入，以及哪些 CLI flags 最重要。

把模糊目標改寫成可用提示詞

較弱的提示詞會說：「幫我的外掛設定 WordPress Playground。」
更強的提示詞會說：「用 wp-playground 為 packages/my-plugin 裡的外掛建立一個可丟棄的本機執行個體，自動掛載專案，針對 WP 6.9 和 PHP 8.3 測試，並告訴我精確的 CLI command，以及任何掛載或 blueprint 需要調整的地方。」

在 wp-playground usage 中，請包含：

• 專案路徑，
• 你要的是 server、run-blueprint 還是 build-snapshot，
• WordPress 與 PHP 版本，
• 程式碼是否要自動掛載，
• 是否需要 Xdebug 或 blueprint 檔。

先選對工作流程

當你要互動式執行個體來做即時測試時，使用 server --auto-mount。當你需要會啟動也會結束的腳本化設定時，使用 run-blueprint。當你想要可重複使用、之後可以交接或重新執行的產物時，使用 build-snapshot。如果你的目標是後端除錯，請直接說明具體失敗模式，並要求提供適合 Xdebug 的步驟，不要只問啟動 command。

依照這個順序閱讀 repo

一份好的 wp-playground guide 會先讀 SKILL.md，再看 references/cli-commands.md 了解 command 的形式；如果需要自動化設定，再看 references/blueprints.md；若任務涉及 breakpoint、mount，或執行卡住，最後再看 references/debugging.md。這個順序能減少猜測，也能避免漏掉像 --mount-before-install 或 --blueprint-may-read-adjacent-files 這類 flags。

wp-playground 技能 FAQ

wp-playground 只適合前端展示嗎？

不是。wp-playground skill 對外掛、佈景主題與後端開發特別有用，尤其是當你需要隔離的 WordPress 行為、可重現的版本，或除錯工作階段時。它比較偏向受控執行，而不是視覺示範。

我一定要先有完整的本機 WordPress 環境嗎？

通常不需要。wp-playground install 的目的，就是提供你一個快速環境，而不用先部署傳統 stack。如果你本來就有本機環境，當你需要乾淨的比較基準，或某個特定 WP/PHP 組合時，wp-playground 依然很有用。

什麼時候不該用它？

不要拿它處理正式資料、需要持續保留內容的工作，或依賴 MySQL-specific 行為的流程。如果你的外掛依賴外部服務、檔案系統持久化，或長時間運作的狀態，wp-playground 可能不是預設的最佳選擇，除非你能在 blueprint 中明確建模這些依賴。

對初學者友善嗎？

是的，只要任務夠單純，而且你有緊跟 CLI 範例。最常失敗的地方是輸入太模糊：如果你沒有指定專案路徑、版本目標，或是否需要 blueprint，結果就會比較不實用。初學者最容易得到好結果的方式，是一次只請它處理一個清楚的工作流程。

如何改善 wp-playground 技能

提供精確的設定變數

最大的品質提升，來自於明確指定專案根目錄、預期的 WP/PHP 版本，以及程式碼要自動掛載還是明確掛載。例如：「用 wp-playground 測試 plugins/contact-form 在 WP 6.9 和 PHP 8.3 下的表現，並使用 --auto-mount」會比「讓它可以運作」有用得多。

描述失敗模式，不要只講目標

如果你是在除錯，請直接說哪裡壞掉：安裝失敗、某個 plugin hook 沒有觸發、REST response 不正確，或只有在 PHP 8.3 才出現的版本相依退化。這能讓技能判斷該用 server、run-blueprint 還是 build-snapshot，也會讓任何 wp-playground for Backend Development 工作流程更有價值。

注意 mount 和 blueprint 的常見錯誤

常見問題包括相對路徑的 mount、必須在安裝前就存在的檔案，以及需要讀取本機鄰近檔案的 blueprints。如果第一次執行失敗，請透過加入絕對路徑、確認是否需要 --mount-before-install，以及說明 blueprint 是否會讀取本機資產，來改善提示詞。若是要除錯，請要求 Xdebug 設定細節，以及預期的 IDE 對應方式。

一次只改一個變數再迭代

如果第一次輸出的結果很接近但還不對，就一次只改一項：WP 版本、PHP 版本、mount 模式，或 blueprint 來源。這樣比較容易判斷問題是出在環境選擇、command flags，還是設定 recipe 本身。