vue-debug-guides

Vue 3 运行时问题、警告、异步失败和水合错误的调试与错误处理。 如需了解开发最佳实践和常见陷阱，请使用 vue-best-practices。

响应式

• 追踪意外的重新渲染和状态更新 → 请参阅 reactivity-debugging-hooks
• 因缺少 .value 访问导致 Ref 值无法更新 → 请参阅 ref-value-access
• 解构响应式对象后，状态停止更新 → 请参阅 reactive-destructuring
• 数组、Maps 或 Sets 中的 Ref 未解包 → 请参阅 refs-in-collections-need-value
• 模板中的嵌套 Ref 渲染为 [object Object] → 请参阅 template-ref-unwrapping-top-level
• 响应式代理的身份比较始终返回 false → 请参阅 reactivity-proxy-identity-hazard
• 第三方实例被代理后出问题 → 请参阅 reactivity-markraw-for-non-reactive
• Watcher 意外地每个 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

模板 Refs

• 元素被条件隐藏时，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-inject-debugging-challenges
• 提供者发生变化时，注入的值不会更新 → 参见 provide-inject-reactivity-not-automatic
• 多个组件共享同一个默认对象 → 参见 provide-inject-default-value-factory

属性

• 内部事件处理器和透传事件处理器都会执行 → 参见 attrs-event-listener-merging
• 显式属性会被透传值覆盖 → 参见 fallthrough-attrs-overwrite-vue3
• 包装组件中的属性会应用到错误的元素上 → 参见 inheritattrs-false-for-wrapper-components

组合式函数

• 在 setup 上下文之外或异步调用组合式函数 → 参见 composable-call-location-restrictions
• 输入变化时，组合式函数的响应式依赖不会更新 → 参见 composable-tovalue-inside-watcheffect
• 组合式函数会意外修改外部状态 → 参见 composable-avoid-hidden-side-effects
• 解构组合式函数的返回值会意外破坏响应性 → 参见 composable-naming-return-pattern

组合式 API

• 异步操作后生命周期钩子静默失效 → 请参阅 composition-api-script-setup-async-context
• 父组件的引用无法访问暴露的属性 → 请参阅 define-expose-before-await
• 函数式编程模式会破坏预期的 Vue 响应式行为 → 请参阅 composition-api-not-functional-programming
• 对 React Hook 的理解导致组合式 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
• 挂载前或 v-if 卸载后，模板引用会因访问 null 而报错 → 请参阅 ts-template-ref-null-handling
• 可选布尔 prop 的行为是 false，而不是 undefined → 请参阅 ts-defineprops-boolean-default-false
• 导入的 defineProps 类型因无法解析或类型引用过于复杂而失败 → 请参阅 ts-defineprops-imported-types-limitations
• 在严格 TypeScript 设置下，未注明类型的 DOM 事件处理程序会报错 → 请参阅 ts-event-handler-explicit-typing
• 动态组件引用会触发响应式组件警告 → 请参阅 ts-shallowref-for-dynamic-components
• 未进行类型收窄时，联合类型的模板表达式无法通过类型检查 → 请参阅 ts-template-type-casting

异步组件

• 使用 defineAsyncComponent 懒加载的路由组件配置错误 → 请参阅 async-component-vue-router
• 加载组件时发生网络故障或超时 → 请参阅 async-component-error-handling
• 组件重新激活后模板引用未定义 → 请参阅 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

• 在 DOM 中找不到 Teleport 目标元素 → 请参阅 teleport-target-must-exist
• Teleport 内容导致 SSR 水合失败 → 请参阅 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（单文件组件）

• 尝试从组件脚本块中使用具名导出 → 请参阅 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

应用配置

• 调用 mount 后应用配置方法无法正常工作 → 请参阅 configure-app-before-mount
• 从 mount() 链式调用应用配置会失败，因为 mount 返回组件实例 → 请参阅 mount-return-value
• 在 Vite 中，基于 require.context 的组件自动注册会失败 → 请参阅 dynamic-component-registration-vite