vue-debug-guides

vue-debug-guides skill 概覽

vue-debug-guides skill 是做什麼用的

vue-debug-guides 是一套專注於 Vue 3 疑難排解的 skill，重點在診斷執行期 bug、警告、非同步載入失敗、reactivity 異常，以及 SSR 或 hydration 不一致等問題。當你手上已經有一個壞掉、怪異，或難以解釋的行為，想比起泛泛的「幫我 debug Vue」更快找到對症的排查路徑時，這個 vue-debug-guides 特別有用。

哪些人適合使用 vue-debug-guides

最適合的是正在維護真實 Vue 3 應用的開發者，尤其是遇到這類症狀時：非預期的 re-render、ref 沒有更新、事件處理器重複觸發、async component 載入失敗、route 載入方式出錯，或 DOM 時序問題。對於不想看大而全框架教學、只想拿到特定問題指引的團隊來說，vue-debug-guides 也特別實用。

真正要完成的工作是什麼

這個 skill 真正要解決的，不是從零開始學 Vue，而是把模糊的 bug 回報，快速收斂到最可能的 Vue 特有陷阱，再套用正確的修正模式，減少反覆試錯。vue-debug-guides 的價值就在於：它會把常見症狀對應到具體 gotcha 與可直接採用的修正範例。

它和一般 prompt 有什麼不同

一般 prompt 常常只會給出很寬泛的 debug 建議。當問題很可能牽涉到 Vue 語意時，vue-debug-guides skill 會更適合，例如 reactivity 規則、computed 的限制、async component 行為、Suspense、keep-alive、fallthrough attrs、event modifiers、nextTick，或 script setup 的限制。這個 repository 就是依照這些典型失敗模式來整理，所以輸出通常會更具體，也更能直接落地。

最值得採用的理由

安裝 vue-debug-guides 最有說服力的理由，是它涵蓋許多高摩擦、又很容易只憑表面症狀誤判的邊界情境。參考內容包含不少實務上很有用的主題，例如 async component 的錯誤處理、為什麼 Vue Router 的 route 不該用 defineAsyncComponent、為什麼 Suspense 可能讓 async component 的 loading 與 error 選項看起來失效，以及為什麼 component refs 可能在 keep-alive 重新啟用後失效。

它不能取代什麼

這個 skill 不能取代 Vue 基礎學習、應用程式 profiling 工具，或官方框架文件。如果你需要的是架構建議、程式風格規範，或廣義的「最佳實務」，repo 本身也有指出 vue-best-practices 會更適合。當你已經碰到失敗、警告，或某個不明顯但不正常的行為，想用 vue-debug-guides for Debugging 來釐清與修正時，它才是對的位置。

如何使用 vue-debug-guides skill

vue-debug-guides 的安裝情境

請從 vuejs-ai/skills repository 安裝到你使用的 skill-enabled 環境中。常見做法如下：

npx skills add vuejs-ai/skills --skill vue-debug-guides

從 repository 可見資訊來看，SKILL.md 裡沒有內建安裝指令，因此如果你是透過 skill 目錄使用，應把它視為 content-first 的 skill：先安裝進 agent 環境，再用具體的 Vue 除錯任務來呼叫它。

先看對的檔案，再開始使用

先讀 skills/vue-debug-guides/SKILL.md，了解它如何從症狀對應到參考內容。接著再打開 reference/ 底下最接近你問題的檔案。很適合優先閱讀的包括：

• reference/async-component-error-handling.md
• reference/async-component-suspense-control.md
• reference/async-component-vue-router.md
• reference/cleanup-side-effects.md
• reference/component-ref-requires-defineexpose.md
• reference/dom-update-timing-nexttick.md
• reference/computed-no-side-effects.md
• reference/attrs-event-listener-merging.md

這個 repo 的重心很明顯在 reference，因此最好的採用方式是把它當成決策樹來用，而不是從頭一路線性讀完的一份指南。

先把 bug 對準最接近的症狀

好的 vue-debug-guides usage，起點是先把症狀描述清楚。不要只說「幫我 debug 這個 component」，而是要說出可觀察到的失敗現象：

• 「Ref 在 script 裡有更新，但 template 顯示還是舊的」
• 「Async route component 一直沒有出現我的 loading UI」
• 「Hydration warning 只在第一次載入時出現」
• 「包過一層的 button，click handler 會觸發兩次」
• 「tab 切換之後，child component ref 上的方法變成 undefined」

這種以症狀為中心的描述方式，能幫助 skill 更快導向對應的 gotcha，而不是回傳一堆通用型 Vue 建議。

讓 skill 發揮效果，需要提供哪些輸入

若要做出更準確的 Vue 專屬診斷，請盡量提供足夠上下文：

• Vue 版本，以及主要生態系組件：Vue Router、Pinia、SSR/Nuxt、Vite
• 問題是只發生在 client、只發生在 SSR，還是只在 hydration 階段出現
• 最小化的 component 或 route 程式碼
• 完整且精確的 warning 或 error 文字
• 你的預期行為與實際行為
• 是否牽涉到 Suspense、keep-alive、async components，或 script setup

少了這些細節，skill 仍然可以提出可能原因，但因為很多 Vue bug 表面症狀很像，輸出品質通常會明顯下降。

把模糊需求改寫成有力的 prompt

弱 prompt：

Use vue-debug-guides to debug why my Vue component is broken.

較強的 prompt：

Use vue-debug-guides to diagnose a Vue 3 issue. In a route component loaded with Vue Router, I wrapped the page in defineAsyncComponent and added loadingComponent, but the loading state never appears and navigation feels inconsistent. We use Vue Router 4 and Vite. Explain the likely mistake, show the correct route lazy-loading pattern, and tell me when Suspense would change the behavior again.

這種寫法有效的原因是：它同時提供了症狀、可疑 API、技術棧背景，以及你希望得到的輸出形式。

vue-debug-guides 的實用操作流程

1. 用一句話描述症狀。
2. 貼上仍可重現問題的最小程式碼範例。
3. 要求 agent 指出最可能違反了哪一條 Vue 專屬規則。
4. 先要一個修正版本，不要一次給五種替代方案。
5. 若有需要，再請它提供一份簡短 checklist，讓你用 DevTools 或 browser console 驗證修正是否生效。

這樣的流程能讓 skill 專注在診斷與修復，不容易一路漂移成泛泛的重構建議。

這個 repo 裡最值得先看的 reference 路徑

有幾份 reference 檔案特別常對應到會浪費大量除錯時間的問題：

• async-component-vue-router.md：route lazy loading 的常見錯法
• async-component-suspense-control.md：為什麼 loadingComponent 和 errorComponent 看起來像被忽略
• async-component-keepalive-ref-issue.md：重新啟用後 ref 消失
• attrs-event-listener-merging.md：fallthrough listeners 導致 click 重複觸發
• computed-no-side-effects.md：把隱性 mutation 寫進 computed getter
• dom-update-timing-nexttick.md：Vue 尚未 flush 更新前就先讀取 DOM

如果你的 bug 剛好落在這些邊界情況附近，那麼安裝 vue-debug-guides 往往很值得，因為一般 prompt 常常會漏掉這些細節。

這些提問方式，能明顯提升輸出品質

請要求 agent 依序完成三件事：

1. 先說出最可能的 Vue 規則或 gotcha。
2. 指出是程式碼中的哪一行或哪種模式觸發了它。
3. 給出最小且安全的修正方式。

這種結構能避免產生冗長、偏猜測性的回答，讓 skill 更像除錯助手，而不是教學型 tutor。

什麼時候該用它，而不是一般 Vue 協助

當 bug 比較像是框架行為造成，而不是你的 business logic 問題時，就該用 vue-debug-guides guide 模式。如果你的問題是「API 回傳資料錯了」，這個 skill 不是主要工具；但如果問題是「watcher 為什麼會意外觸發」、「ref 為什麼是 undefined」、「transition 為什麼有延遲」、「route component 載入表現很奇怪」，那它就非常對位。

vue-debug-guides skill 常見問題

vue-debug-guides 適合初學者嗎

可以，但前提是這位初學者手上已經有具體 bug。這些 reference 很實務、也偏範例導向。不過，如果你是要從零理解 Vue 概念，它不是最理想的第一份資源，因為整份內容是依照失敗情境來編排，不是照教學順序鋪陳。

vue-debug-guides 最擅長處理哪些 bug

vue-debug-guides 最強的範圍是 Vue 3 執行期除錯：reactivity 邊界案例、computed 的錯誤用法、watcher 行為、async component 失敗、DOM 更新時序、event 與 attrs 合併，以及像 keep-alive 或 Suspense 這類 component lifecycle 互動問題。

它能協助處理 SSR 和 hydration 問題嗎

可以。skill 描述中已明確涵蓋 SSR 與 hydration 類型的 bug。這點很重要，因為 hydration 失敗通常需要 Vue 專屬的推理方式，不是一般前端除錯建議就能解決。不過你仍然應該提供精確的 warning 文字，並說清楚 mismatch 是只在 production 發生，還是只在第一次 render 時出現。

它和一般 prompting 的差異在哪裡

一般 prompting 很容易只給出像「檢查你的 state」這種籠統建議。當答案仰賴已知的 Vue gotcha 時，vue-debug-guides skill 的價值會明顯更高，例如 template 中 top-level ref 的 unwrapping 規則、同一個 tick 內批次更新的行為，或 route component 載入模式與一般 async component 不同這類細節。

遇到 Vue Router 問題，也該用它嗎

可以，只要 router 問題跟 component 載入、transition，或 render timing 有交集，就很適合。它其中一份很有用的 reference 就在說明：route component 應直接使用 dynamic imports，而不是 defineAsyncComponent，這也是很多人最容易混淆的地方。

什麼情況下 vue-debug-guides 不適合

如果你要處理的是 design systems、應用架構、state modeling，或與 Vue 語意無關的一般 JavaScript 錯誤，那它就不是理想選擇。當你需要的是 coding standards，而不是除錯導向的指引時，它也不會是最好的工具。

如何提升 vue-debug-guides skill 的效果

給 vue-debug-guides 一個可重現的症狀

想更快拿到好結果，最有效的方法就是提供 minimal reproduction。請附上仍能重現問題的最小 component、route config，或 composable。這樣 skill 才能把你的案例對應到現有 reference，而不是從一大段程式碼庫裡猜。

直接點出用到哪些 Vue 功能

請明確說明你的程式碼是否使用了：

• script setup
• defineAsyncComponent
• Suspense
• keep-alive
• Vue Router
• SSR 或 hydration
• composables、watchers，或 computed values

這些資訊能大幅縮小判斷範圍，很多時候甚至能直接對到某一篇 guide。

提供完整警告訊息，不要只用自己的說法轉述

像「Vue 好像有提到 hydration 的問題」這種轉述，遠不如貼出完整 console 訊息來得有用。這個 skill 本來就是依照特定錯誤類型來建構的，因此原始 warning 文字越完整，匹配品質越好，也越能避免修錯方向。

先要診斷，再談重構

常見失敗模式之一，就是太早要求整段重寫。更好的 prompt 寫法是：

Use vue-debug-guides to identify the likely Vue rule being broken here, explain why this symptom happens, and then show the smallest fix.

這種順序通常比一開始就要求完整 refactor，更容易得到乾淨而精準的答案。

同時說明預期行為與實際行為

不要只貼程式碼，請一併說明：

• 你原本預期會發生什麼
• 實際上發生了什麼
• 問題是穩定重現還是偶發
• 是否在加入 Suspense 或 keep-alive 之類的 Vue 功能後才開始改變

這些對照能幫 skill 分辨你遇到的是邏輯 bug，還是框架互動造成的 bug。

第一輪回答後，再做一次收斂追問

如果第一輪輸出已經接近，但還不夠，就用更聚焦的 follow-up：

• 「現在假設這個 component 在 <Suspense> 裡面。」
• 「現在把 SSR hydration 也納入考量。」
• 「現在解釋為什麼 event 會觸發兩次。」
• 「現在示範如何用 Vue DevTools 驗證修正。」

這是從 vue-debug-guides for Debugging 挖出更深價值的最好方式，同時又不會把請求擴得太散。

注意幾種常見的失敗用法

在以下情況下，結果通常會比較差：

• 貼了太多無關程式碼
• 沒有提供 error message
• 沒有說明是否牽涉 routing 或 SSR
• 一次問「所有可能原因」
• 把 debugging、refactoring、architecture 目標混在同一個請求裡

請讓任務保持聚焦。這個 skill 最擅長的，是有證據基礎、以診斷為核心的問題。

把 reference 資料夾當成第二步的查核來源

當 agent 指出最可能的原因後，請打開它引用的 markdown 檔案，拿你的程式碼去對照其中的「bad」與「good」模式。在這個 repo 裡，真正有深度的內容其實都在 reference/ 檔案中。最好的 vue-debug-guides guide 使用流程，往往是：先找出可能主題、讀一篇對應檔案、套用修正，若還需要，再回來做第二輪 prompt。