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 对象的恒等比较恒为 false → 参见 reactivity-proxy-identity-hazard
• 第三方库实例被响应式代理后出现异常/失效 → 参见 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-no-parameters

Watchers

• 异步操作返回陈旧数据导致覆盖最新结果 → 参见 watch-async-cleanup
• 在异步回调函数内部创建侦听器导致内存泄漏 → 参见 watch-async-creation-memory-leak
• 侦听器对响应式对象的属性始终无法触发 → 参见 watch-reactive-property-getter
• 异步 watchEffect 在 await 之后丢失依赖追踪 → 参见 watcheffect-async-dependency-tracking
• 侦听器回调中读取到的 DOM 数据为旧数据 → 参见 watch-flush-timing
• 深度侦听（Deep Watcher）拿到的新旧值引用相同 → 参见 watch-deep-same-object-reference
• watchEffect 在模板引用（Template Ref）更新前就已运行 → 参见 watcheffect-flush-post-for-refs

Components

• 子组件抛出“未找到组件（component not found）”错误 → 参见 local-components-not-in-descendants
• 自定义组件上的点击事件监听不触发 → 参见 click-events-on-components
• 父组件在 script setup 中无法访问子组件 ref 数据 → 参见 component-ref-requires-defineexpose
• DOM 原生 HTML 解析破坏 Vue 组件语法 → 参见 in-dom-template-parsing-caveats
• 因组件命名冲突导致渲染了错误的组件 → 参见 component-naming-conflicts
• 父组件样式无法应用到多根节点（Multi-root）组件上 → 参见 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

Templates

• 在模板表达式中使用复杂语句导致编译报错 → 参见 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 导致优先级 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
• 范围遍历时出现 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
• 重构模板 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
• 中文/日文拼音输入法下实时搜索/校验失效 → 参见 v-model-ime-composition
• 数字输入框返回空字符串而不是数字 0 → 参见 v-model-number-modifier-behavior
• 自定义 Checkbox 勾选值在表单提交时未正确发送 → 参见 checkbox-true-false-value-form-submission

Events & Modifiers

• 链式组合多个事件修饰符导致非预期行为 → 参见 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
• 在异步回调中注册生命周期钩子导致其永远不执行 → 参见 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
• 作用域插槽 Props 缺少预期名称属性 → 参见 slot-name-reserved-prop
• 嵌套封装组件打断了子插槽透传功能 → 参见 slot-forwarding-to-child-components

Provide/Inject

• 异步操作完成后调用 provide 静默失效 → 参见 provide-inject-synchronous-setup
• 排查 provide 注入值的来源追溯困难 → 参见 provide-inject-debugging-challenges
• Provider 数据更新后 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 在 await 前无法访问子组件暴露的属性 → 参见 define-expose-before-await
• 函数式编程模式打断了 Vue 预期的响应式机制 → 参见 [composition-api-not-functional-programming](reference/composition