vue-debug-guides

Vue 3 除錯與錯誤處理，針對執行時期問題、警告、非同步失敗及 Hydration 錯誤。
如需開發最佳實踐與常見陷阱，請使用 vue-best-practices。

響應式

• 追蹤非預期的重新渲染與狀態更新 → 請參閱 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
• 響應式代理的身分比較總是回傳 false → 請參閱 reactivity-proxy-identity-hazard
• 第三方實例被代理後出現異常 → 請參閱 reactivity-markraw-for-non-reactive
• 監聽器在每個 tick 中意外只觸發一次 → 請參閱 reactivity-same-tick-batching

計算屬性

• 計算屬性的 getter 意外觸發突變或請求 → 請參閱 computed-no-side-effects
• 修改計算屬性值導致變更消失 → 請參閱 computed-return-value-readonly
• 條件邏輯後計算屬性值從未更新 → 請參閱 computed-conditional-dependencies
• 排序或反轉陣列破壞原始狀態 → 請參閱 computed-array-mutation
• 傳遞參數給計算屬性失敗 → 請參閱 computed-no-parameters

監聽器

• 非同步操作被過時資料覆蓋 → 請參閱 watch-async-cleanup
• 在非同步回呼中建立監聽器 → 請參閱 watch-async-creation-memory-leak
• 監聽器從未觸發響應式物件屬性 → 請參閱 watch-reactive-property-getter
• 非同步 watchEffect 在 await 後遺漏依賴 → 請參閱 watcheffect-async-dependency-tracking
• 監聽器回呼中的 DOM 讀取為過時值 → 請參閱 watch-flush-timing
• 深度監聽器回報相同的新舊值 → 請參閱 watch-deep-same-object-reference
• watchEffect 在模板 ref 更新前執行 → 請參閱 watcheffect-flush-post-for-refs

元件

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

Props 與 Emits

• defineProps 中參考的變數導致錯誤 → 請參閱 prop-defineprops-scope-limitation
• 元件發出未宣告的事件導致警告 → 請參閱 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

模板

• 使用陳述式時出現模板編譯錯誤 → 請參閱 template-expressions-restrictions
• 「Cannot read property of undefined」執行時期錯誤 → 請參閱 v-if-null-check-order
• 動態指令引數無法正常運作 → 請參閱 dynamic-argument-constraints
• v-else 元素總是無條件渲染 → 請參閱 v-else-must-follow-v-if
• 混合 v-if 與 v-for 導致優先級錯誤與遷移問題 → 請參閱 no-v-if-with-v-for
• 模板函式呼叫突變狀態導致不可預測的重新渲染錯誤 → 請參閱 template-functions-no-side-effects
• 迴圈中的子元件顯示未定義資料 → 請參閱 v-for-component-props
• 排序或反轉後陣列順序改變 → 請參閱 v-for-computed-reverse-sort
• 列表項目意外消失或狀態交換 → 請參閱 v-for-key-attribute
• 範圍迭代時出現差一錯誤 → 請參閱 v-for-range-starts-at-one
• v-show 或 v-else 在 template 元素上無效 → 請參閱 v-show-template-limitation

模板 Ref

• 元素條件隱藏時 ref 變為 null → 請參閱 template-ref-null-with-v-if
• 迴圈中 ref 陣列索引與資料陣列不匹配 → 請參閱 template-ref-v-for-order
• 重構模板 ref 名稱時程式碼無聲中斷 → 請參閱 use-template-ref-vue35

表單與 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
• 中文/日文輸入的即時搜尋/驗證異常 → 請參閱 v-model-ime-composition
• 數字輸入回傳空字串而非零 → 請參閱 v-model-number-modifier-behavior
• 自訂核取方塊值未在表單中提交 → 請參閱 checkbox-true-false-value-form-submission

事件與修飾符

• 串聯多個事件修飾符產生非預期結果 → 請參閱 event-modifier-order-matters
• 鍵盤快捷鍵搭配系統修飾鍵時未觸發 → 請參閱 keyup-modifier-timing
• 鍵盤快捷鍵觸發非預期的修飾鍵組合 → 請參閱 exact-modifier-for-precise-shortcuts
• 合併 passive 與 prevent 修飾符破壞事件行為 → 請參閱 no-passive-with-prevent

生命週期

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

插槽

• 在插槽內容中存取子元件資料回傳 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
• 作用域插槽 props 缺少預期的 name 屬性 → 請參閱 slot-name-reserved-prop
• 包裝元件破壞子插槽功能 → 請參閱 slot-forwarding-to-child-components

Provide/Inject

• 非同步操作後呼叫 provide 無聲失敗 → 請參閱 provide-inject-synchronous-setup
• 追蹤 provide 值的來源 → 請參閱 provide-inject-debugging-challenges
• 提供者變更時 inject 值未更新 → 請參閱 provide-inject-reactivity-not-automatic
• 多個元件共用同一個預設物件 → 請參閱 provide-inject-default-value-factory

Attrs

• 內部與穿透事件處理器同時執行 → 請參閱 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

• 非同步操作後生命週期鉤子無聲失敗 → 請參閱 composition-api-script-setup-async-context
• 父元件 ref 無法存取暴露的屬性 → 請參閱 define-expose-before-await
• 函數式程式設計模式破壞預期的 Vue 響應式行為 → 請參閱 composition-api-not-functional-programming
• React Hook 心智模型導致 Composition API 使用錯誤 → 請參閱 composition-api-vs-react-hooks-differences

動畫

• DOM 節點重複使用時動畫未觸發 → 請參閱 animation-key-for-rerender
• TransitionGroup 列表更新在負載下感覺延遲 → 請參閱 animation-transitiongroup-performance

TypeScript

• 可變 prop 預設值在元件實例間洩漏狀態 → 請參閱 ts-withdefaults-mutable-factory-function
• reactive() 泛型型別導致 ref 解包不匹配 → 請參閱 ts-reactive-no-generic-argument
• 模板 ref 在掛載前或 v-if 卸載後拋出 null 存取錯誤 → 請參閱 ts-template-ref-null-handling
• 可選布林 prop 表現為 false 而非 undefined → 請參閱 ts-defineprops-boolean-default-false
• 匯入的 defineProps 型別因無法解析或複雜型別參考而失敗 → 請參閱 ts-defineprops-imported-types-limitations
• 未型別的 DOM 事件處理器在嚴格 TypeScript 設定下失敗 → 請參閱 ts-event-handler-explicit-typing
• 動態元件 ref 觸發響應式元件警告 → 請參閱 ts-shallowref-for-dynamic-components
• 聯集型別的模板表達式未經縮小型別檢查失敗 → 請參閱 ts-template-type-casting

非同步元件

• 路由元件搭配 defineAsyncComponent 延遲載入設定錯誤 → 請參閱 async-component-vue-router
• 載入元件時網路失敗或逾時 → 請參閱 async-component-error-handling
• 元件重新啟用後模板 ref 為 undefined → 請參閱 async-component-keepalive-ref-issue

渲染函式

• 狀態變更後渲染函式輸出保持靜態 → 請參閱 rendering-render-function-return-from-setup
• 重複使用的 vnode 實例渲染錯誤 → 請參閱 render-function-vnodes-must-be-unique
• 字串元件名稱渲染為 HTML 元素 → 請參閱 rendering-resolve-component-for-string-names
• 存取 vnode 內部屬性在 Vue 更新時中斷 → 請參閱 render-function-avoid-internal-vnode-properties
• Vue 2 渲染函式模式在 Vue 3 中崩潰 → 請參閱 rendering-render-function-h-import-vue3
• 從 h() 渲染的插槽內容未顯示 → 請參閱 rendering-render-function-slots-as-functions

KeepAlive

• 巢狀 Vue Router 路由中子元件掛載兩次 → 請參閱 keepalive-router-nested-double-mount
• 結合 KeepAlive 與 Transition 動畫時記憶體增長 → 請參閱 keepalive-transition-memory-leak

過渡效果

• JavaScript 過渡鉤子因缺少 done 回呼而卡住 → 請參閱 transition-js-hooks-done-callback
• 行內列表元素的移動動畫失敗 → 請參閱 transition-group-flip-inline-elements
• 列表項目跳動而非平滑動畫 → 請參閱 transition-group-move-animation-position-absolute
• Vue 2 到 Vue 3 TransitionGroup 包裝變更破壞佈局 → 請參閱 transition-group-no-default-wrapper-vue3
• 巢狀過渡在完成前中斷 → 請參閱 transition-nested-duration
• 作用域樣式在可重複使用的過渡包裝中失效 → 請參閱 transition-reusable-scoped-style
• RouterView 過渡在首次渲染時意外動畫 → 請參閱 transition-router-view-appear
• 混合 CSS 過渡與動畫導致時間問題 → 請參閱 transition-type-when-mixed
• 快速過渡切換時遺漏清理鉤子 → 請參閱 transition-unmount-hook-timing

Teleport

• Teleport 目標元素在 DOM 中找不到 → 請參閱 teleport-target-must-exist
• Teleport 內容破壞 SSR Hydration → 請參閱 teleport-ssr-hydration
• 作用域樣式未套用至 Teleport 內容 → 請參閱 teleport-scoped-styles-limitation

Suspense

• 需要處理 Suspense 元件的非同步錯誤 → 請參閱 suspense-no-builtin-error-handling
• 搭配伺服端渲染使用 Suspense → 請參閱 suspense-ssr-hydration-issues
• Suspense 下非同步元件載入/錯誤 UI 被忽略 → 請參閱 async-component-suspense-control

SSR

• 伺服端與用戶端渲染的 HTML 不一致 → 請參閱 ssr-hydration-mismatch-causes
• 共用單例儲存導致請求間使用者狀態洩漏 → 請參閱 state-ssr-cross-request-pollution
• 僅瀏覽器 API 在通用程式碼路徑中導致伺服端渲染崩潰 → 請參閱 ssr-platform-specific-apis

效能

• 父元件傳遞不穩定 props 導致列表子元件不必要地重新渲染 → 請參閱 perf-props-stability-update-optimization
• 計算屬性物件儘管值相等仍重新觸發副作用 → 請參閱 perf-computed-object-stability

SFC（單一檔案元件）

• 嘗試從元件 script 區塊使用具名匯出 → 請參閱 sfc-named-exports-forbidden
• 變更後模板中的變數未更新 → 請參閱 sfc-script-setup-reactivity
• 作用域樣式未套用至子元件元素 → 請參閱 sfc-scoped-css-child-component-styling
• 作用域樣式未套用至動態 v-html 內容 → 請參閱 sfc-scoped-css-dynamic-content
• 作用域樣式未套用至插槽內容 → 請參閱 sfc-scoped-css-slot-content
• 動態建構時 Tailwind 類別遺失 → 請參閱 tailwind-dynamic-class-generation
• 遞迴元件因名稱衝突未渲染 → 請參閱 self-referencing-component-name

外掛

• 除錯全域屬性導致命名衝突 → 請參閱 plugin-global-properties-sparingly
• 外掛未運作或 inject 回傳 undefined → 請參閱 plugin-install-before-mount
• 外掛全域屬性在 setup 為基礎的元件中不可用 → 請參閱 plugin-prefer-provide-inject-over-global-properties
• 外掛型別擴充錯誤破壞 ComponentCustomProperties 型別 → 請參閱 plugin-typescript-type-augmentation

應用程式設定

• 掛載後應用程式設定方法無效 → 請參閱 configure-app-before-mount
• 從 mount() 串聯應用程式設定失敗，因為 mount 回傳元件實例 → 請參閱 mount-return-value
• 基於 require.context 的元件自動註冊在 Vite 中失敗 → 請參閱 dynamic-component-registration-vite