vue-debug-guides

Vue 3 除錯與錯誤處理指南，涵蓋執行階段問題、警告、非同步失敗及 Hydration Bug。
如需開發最佳實踐與常見踩坑點，請使用 vue-best-practices。

Reactivity

• 追蹤非預期的重新渲染與狀態更新 → 參閱 reactivity-debugging-hooks
• 因漏寫 .value 存取導致 Ref 值未更新 → 參閱 ref-value-access
• 解構響應式物件後狀態停止更新 → 參閱 reactive-destructuring
• 陣列、Map 或 Set 內部的 Ref 未自動解包 → 參閱 refs-in-collections-need-value
• 模板中的巢狀 Ref 被渲染為 [object Object] → 參閱 template-ref-unwrapping-top-level
• 響應式 Proxy 的全等比較（Identity Comparison）總是回傳 false → 參閱 reactivity-proxy-identity-hazard
• 第三方套件實例經 Proxy 包裹後失效 → 參閱 reactivity-markraw-for-non-reactive
• Watcher 在同一個 tick 內非預期地僅觸發一次 → 參閱 reactivity-same-tick-batching

Computed

• Computed getter 非預期地觸發狀態修改或請求 → 參閱 computed-no-side-effects
• 直接修改 Computed 值導致變更消失 → 參閱 computed-return-value-readonly
• 條件邏輯分支後的 Computed 值不再更新 → 參閱 computed-conditional-dependencies
• 對陣列進行排序或反轉破壞了原始狀態 → 參閱 computed-array-mutation
• 嘗試向計算屬性（Computed Property）傳遞參數失敗 → 參閱 computed-no-parameters

Watchers

• 非同步操作使用舊資料覆蓋了新狀態 → 參閱 watch-async-cleanup
• 在非同步回呼函式中建立 Watcher 導致記憶體洩漏 → 參閱 watch-async-creation-memory-leak
• Watcher 從未觸發響應式物件屬性的變更 → 參閱 watch-reactive-property-getter
• 非同步 watchEffect 在 await 之後遺失依賴追蹤 → 參閱 watcheffect-async-dependency-tracking
• 在 Watcher 回呼函式內讀取的 DOM 仍為舊值 → 參閱 watch-flush-timing
• 深層 Watcher 報告的新舊值回傳相同物件參照 → 參閱 watch-deep-same-object-reference
• watchEffect 在 Template Ref 更新前就執行了 → 參閱 watcheffect-flush-post-for-refs

Components

• 子元件拋出 "component not found" 錯誤 → 參閱 local-components-not-in-descendants
• 自訂元件上的點擊監聽器（Click Listener）未觸發 → 參閱 click-events-on-components
• 父元件在 script setup 中無法讀取子元件的 Ref 資料 → 參閱 component-ref-requires-defineexpose
• HTML 模板解析破壞了 Vue 元件語法 → 參閱 in-dom-template-parsing-caveats
• 因名稱衝突導致渲染了錯誤的元件 → 參閱 component-naming-conflicts
• 父元件樣式無法套用至多根節點（Multi-root）元件 → 參閱 multi-root-component-class-attrs

Props & Emits

• 在 defineProps 中引用的變數引發錯誤 → 參閱 prop-defineprops-scope-limitation
• 元件發送（Emit）未宣告的事件引發控制台警告 → 參閱 declare-emits-for-documentation
• 在函式或條件判斷式中呼叫 defineEmits → 參閱 defineEmits-must-be-top-level
• defineEmits 同時使用了型別與執行階段引數 → 參閱 defineEmits-no-runtime-and-type-mixed
• 原生事件監聽器對點擊事件無回應 → 參閱 native-event-collision-with-emits
• 點擊時元件事件觸發了兩次 → 參閱 undeclared-emits-double-firing

Templates

• 模板表達式包含敘述句（Statement）導致編譯錯誤 → 參閱 template-expressions-restrictions
• 出現 "Cannot read property of undefined" 執行階段錯誤 → 參閱 v-if-null-check-order
• 動態指令引數（Dynamic directive arguments）無法正常工作 → 參閱 dynamic-argument-constraints
• v-else 元素總是無條件地被渲染 → 參閱 v-else-must-follow-v-if
• 混合使用 v-if 與 v-for 導致優先順序 Bug 與版本升級毀損 → 參閱 no-v-if-with-v-for
• 模板中呼叫的函式修改了狀態，導致不可預測的重新渲染 Bug → 參閱 template-functions-no-side-effects
• 迴圈中的子元件顯示 undefined 資料 → 參閱 v-for-component-props
• 排序或反轉後陣列順序出錯 → 參閱 v-for-computed-reverse-sort
• 清單項目非預期地消失或狀態錯位 → 參閱 v-for-key-attribute
• 範圍迭代（Range Iteration）出現 Off-by-one 偏差錯誤 → 參閱 v-for-range-starts-at-one
• v-show 或 v-else 無法在 <template> 元素上作用 → 參閱 v-show-template-limitation

Template Refs

• 當元素透過條件隱藏時 Ref 變成 null → 參閱 template-ref-null-with-v-if
• 迴圈中的 Ref 陣列索引與資料陣列不一致 → 參閱 template-ref-v-for-order
• 重構 Template Ref 名稱導致程式碼靜默失效 → 參閱 use-template-ref-vue35

Forms & v-model

• 使用 v-model 時未顯示表單初始值 → 參閱 v-model-ignores-html-attributes
• Textarea 內容變更未同步更新 Ref → 參閱 textarea-no-interpolation
• iOS 使用者無法選擇下拉選單的第一個選項 → 參閱 select-initial-value-ios-bug
• 父子元件之間的數值不一致 → 參閱 define-model-default-value-sync
• 物件屬性變更未同步給父元件 → 參閱 definemodel-object-mutation-no-emit
• 中日文輸入（IME 組字）時即時搜尋/驗證失效 → 參閱 v-model-ime-composition
• 數字輸入欄位回傳空字串而非零 → 參閱 v-model-number-modifier-behavior
• 自訂核取方塊（Checkbox）數值未成功提交至表單 → 參閱 checkbox-true-false-value-form-submission

Events & Modifiers

• 串接多個事件修飾符（Event Modifier）產生非預期結果 → 參閱 event-modifier-order-matters
• 結合系統修飾鍵時快捷鍵未觸發 → 參閱 keyup-modifier-timing
• 快捷鍵在未預期的修飾鍵組合下意外觸發 → 參閱 exact-modifier-for-precise-shortcuts
• 同時使用 passive 與 prevent 修飾符破壞了事件行為 → 參閱 no-passive-with-prevent

Lifecycle

• 未移除的事件監聽器導致記憶體洩漏 → 參閱 cleanup-side-effects
• 元件掛載前存取 DOM 失敗 → 參閱 lifecycle-dom-access-timing
• 狀態變更後讀取的 DOM 仍為舊值 → 參閱 dom-update-timing-nexttick
• SSR 渲染結果與用戶端 Hydration 不一致 → 參閱 lifecycle-ssr-awareness
• 非同步註冊的生命週期 Hook 從未執行 → 參閱 lifecycle-hooks-synchronous-registration

Slots

• 在插槽內容中存取子元件資料回傳 undefined 數值 → 參閱 slot-render-scope-parent-only
• 混合使用具名插槽與作用域插槽引發編譯錯誤 → 參閱 slot-named-scoped-explicit-default
• 在原生 HTML 元素上使用 v-slot 引發編譯錯誤 → 參閱 slot-v-slot-on-components-or-templates-only
• 隱式預設插槽行為導致內容位置非預期 → 參閱 slot-implicit-default-content
• 作用域插槽 Prop 遺失預期的 name 屬性 → 參閱 slot-name-reserved-prop
• 包裝元件（Wrapper Component）破壞了子元件插槽功能 → 參閱 slot-forwarding-to-child-components

Provide/Inject

• 在非同步操作後呼叫 provide 靜默失敗 → 參閱 provide-inject-synchronous-setup
• 追蹤 Provided 數值的來源 → 參閱 provide-inject-debugging-challenges
• Provider 變更時 Injected 數值未同步更新 → 參閱 provide-inject-reactivity-not-automatic
• 多個元件共享同一個預設物件 → 參閱 provide-inject-default-value-factory

Attrs

• 內部與透傳（Fallthrough）的事件處理常式皆被執行 → 參閱 attrs-event-listener-merging
• 顯式定義的屬性被透傳屬性覆蓋 → 參閱 fallthrough-attrs-overwrite-vue3
• 包裝元件中的屬性套用至錯誤的元素 → 參閱 inheritattrs-false-for-wrapper-components

Composables

• 在 setup 上下文之外或非同步地呼叫 Composable → 參閱 composable-call-location-restrictions
• 輸入變更時 Composable 的響應式依賴未更新 → 參閱 composable-tovalue-inside-watcheffect
• Composable 非預期地修改了外部狀態 → 參閱 composable-avoid-hidden-side-effects
• 解構 Composable 回傳值非預期地破壞了響應性 → 參閱 composable-naming-return-pattern

Composition API

• 非同步操作後生命週期 Hook 靜默失效 → 參閱 composition-api-script-setup-async-context
• 父元件 Ref 無法讀取子元件暴露的屬性 → 參閱 define-expose-before-await
• 函數式程式設計模式破壞了預期的 Vue 響應式行為 → 參閱 [composition-api-not-functional-programming](reference/composition