Back to Details

vue-debug-guides

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
Vue 3 debugging and error handling for runtime issues, warnings, async failures, and hydration bugs. For development best practices and common gotchas, use 
vue-best-practices
.
针对运行时问题、警告、异步失败以及水合bug的Vue 3调试与错误处理。 如需了解开发最佳实践和常见陷阱，请使用
vue-best-practices
。

Reactivity

响应式

  • Tracing unexpected re-renders and state updates → See reactivity-debugging-hooks
  • 追踪意外重渲染与状态更新 → 查看reactivity-debugging-hooks

Watchers

监听器

  • Async operations overwriting with stale data → See watch-async-cleanup
  • Creating watchers inside async callbacks → See watch-async-creation-memory-leak
  • 异步操作使用过期数据覆盖内容 → 查看watch-async-cleanup
  • 在异步回调中创建监听器 → 查看watch-async-creation-memory-leak

Components

组件

  • Child component throws "component not found" error → See local-components-not-in-descendants
  • Click listener doesn't fire on custom component → See click-events-on-components
  • Parent can't access child ref data in script setup → See component-ref-requires-defineexpose
  • HTML template parsing breaks Vue component syntax → See in-dom-template-parsing-caveats
  • Wrong component renders due to naming collisions → See component-naming-conflicts
  • Parent styles don't apply to multi-root component → See multi-root-component-class-attrs
  • 子组件抛出“组件未找到”错误 → 查看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

Props & 事件触发

  • Variables referenced in defineProps cause errors → See prop-defineprops-scope-limitation
  • Component emits undeclared event causing warnings → See declare-emits-for-documentation
  • defineEmits used inside function or conditional → See defineEmits-must-be-top-level
  • defineEmits has both type and runtime arguments → See defineEmits-no-runtime-and-type-mixed
  • Native event listeners not responding to clicks → See native-event-collision-with-emits
  • Component event fires twice when clicking → See undeclared-emits-double-firing
  • 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

模板

  • Getting template compilation errors with statements → See template-expressions-restrictions
  • "Cannot read property of undefined" runtime errors → See v-if-null-check-order
  • Dynamic directive arguments not working properly → See dynamic-argument-constraints
  • v-else elements rendering unconditionally always → See v-else-must-follow-v-if
  • Child components in loops showing undefined data → See v-for-component-props
  • Array order changing after sorting or reversing → See v-for-computed-reverse-sort
  • List items disappearing or swapping state unexpectedly → See v-for-key-attribute
  • Getting off-by-one errors with range iteration → See v-for-range-starts-at-one
  • v-show or v-else not working on template elements → See v-show-template-limitation
  • 语句导致模板编译错误 → 查看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-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

Template Refs

模板Ref

  • Ref becomes null when element is conditionally hidden → See template-ref-null-with-v-if
  • Ref array indices don't match data array in loops → See template-ref-v-for-order
  • Refactoring template ref names breaks silently in code → See use-template-ref-vue35
  • 元素被条件隐藏时Ref变为null → 查看template-ref-null-with-v-if
  • 循环中Ref数组索引与数据数组不匹配 → 查看template-ref-v-for-order
  • 重构模板Ref名称导致代码静默失效 → 查看use-template-ref-vue35

Forms & v-model

表单与v-model

  • Initial form values not showing when using v-model → See v-model-ignores-html-attributes
  • Textarea content changes not updating the ref → See textarea-no-interpolation
  • iOS users cannot select dropdown first option → See select-initial-value-ios-bug
  • Parent and child components have different values → See define-model-default-value-sync
  • Object property changes not syncing to parent → See definemodel-object-mutation-no-emit
  • Real-time search/validation broken for Chinese/Japanese input → See v-model-ime-composition
  • Number input returns empty string instead of zero → See v-model-number-modifier-behavior
  • Custom checkbox values not submitted in forms → See checkbox-true-false-value-form-submission
  • 使用v-model时初始表单值不显示 → 查看v-model-ignores-html-attributes
  • 文本框内容更改未更新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-true-false-value-form-submission

Events & Modifiers

事件与修饰符

  • Chaining multiple event modifiers produces unexpected results → See event-modifier-order-matters
  • Keyboard shortcuts don't fire with system modifier keys → See keyup-modifier-timing
  • 链式调用多个事件修饰符产生意外结果 → 查看event-modifier-order-matters
  • 键盘快捷键搭配系统修饰键时不触发 → 查看keyup-modifier-timing

Lifecycle

生命周期

  • Memory leaks from unremoved event listeners → See cleanup-side-effects
  • DOM access fails before component mounts → See lifecycle-dom-access-timing
  • DOM reads return stale values after state changes → See dom-update-timing-nexttick
  • SSR rendering differs from client hydration → See lifecycle-ssr-awareness
  • 未移除的事件监听器导致内存泄漏 → 查看cleanup-side-effects
  • 组件挂载前DOM访问失败 → 查看lifecycle-dom-access-timing
  • 状态更改后DOM读取返回过期值 → 查看dom-update-timing-nexttick
  • SSR渲染与客户端水合不一致 → 查看lifecycle-ssr-awareness

Slots

插槽

  • Wrapper components breaking child slot functionality → See slot-forwarding-to-child-components
  • 包装组件破坏子组件插槽功能 → 查看slot-forwarding-to-child-components

Provide/Inject

Provide/Inject

  • Calling provide after async operations fails silently → See provide-inject-synchronous-setup
  • Tracing where provided values come from → See provide-inject-debugging-challenges
  • Injected values not updating when provider changes → See provide-inject-reactivity-not-automatic
  • Multiple components share same default object → See provide-inject-default-value-factory
  • 异步操作后调用provide静默失败 → 查看provide-inject-synchronous-setup
  • 追踪提供值的来源 → 查看provide-inject-debugging-challenges
  • 提供者更改时注入值未更新 → 查看provide-inject-reactivity-not-automatic
  • 多个组件共享同一个默认对象 → 查看provide-inject-default-value-factory

Attrs

属性透传

  • Both internal and fallthrough event handlers execute → See attrs-event-listener-merging
  • Explicit attributes overwritten by fallthrough values → See fallthrough-attrs-overwrite-vue3
  • Attributes applying to wrong element in wrappers → See inheritattrs-false-for-wrapper-components
  • 内部和透传事件监听器均执行 → 查看attrs-event-listener-merging
  • 显式属性被透传值覆盖 → 查看fallthrough-attrs-overwrite-vue3
  • 包装组件中属性应用到错误元素 → 查看inheritattrs-false-for-wrapper-components

Composables

组合式函数

  • Composable called outside setup context or asynchronously → See composable-call-location-restrictions
  • Composable reactive dependency not updating when input changes → See composable-tovalue-inside-watcheffect
  • 在setup上下文外或异步调用组合式函数 → 查看composable-call-location-restrictions
  • 输入更改时组合式函数响应式依赖未更新 → 查看composable-tovalue-inside-watcheffect

Composition API

组合式API

  • Lifecycle hooks failing silently after async operations → See composition-api-script-setup-async-context
  • Parent component refs unable to access exposed properties → See define-expose-before-await
  • 异步操作后生命周期钩子静默失败 → 查看composition-api-script-setup-async-context
  • 父组件Ref无法访问暴露的属性 → 查看define-expose-before-await

Async Components

异步组件

  • Network failures or timeouts loading components → See async-component-error-handling
  • Template refs undefined after component reactivation → See async-component-keepalive-ref-issue
  • 加载组件时出现网络故障或超时 → 查看async-component-error-handling
  • 组件重新激活后模板Ref未定义 → 查看async-component-keepalive-ref-issue

Teleport

Teleport

  • Teleport target element not found in DOM → See teleport-target-must-exist
  • Teleported content breaks SSR hydration → See teleport-ssr-hydration
  • Teleport目标元素在DOM中不存在 → 查看teleport-target-must-exist
  • Teleport内容破坏SSR水合 → 查看teleport-ssr-hydration

Suspense

Suspense

  • Need to handle async errors from Suspense components → See suspense-no-builtin-error-handling
  • Using Suspense with server-side rendering → See suspense-ssr-hydration-issues
  • 需要处理Suspense组件的异步错误 → 查看suspense-no-builtin-error-handling
  • 在服务端渲染中使用Suspense → 查看suspense-ssr-hydration-issues

SSR

SSR

  • HTML differs between server and client renders → See ssr-hydration-mismatch-causes
  • 服务端与客户端渲染的HTML不一致 → 查看ssr-hydration-mismatch-causes

SFC (Single File Components)

单文件组件(SFC)

  • Trying to use named exports from component script blocks → See sfc-named-exports-forbidden
  • Variables not updating in template after changes → See sfc-script-setup-reactivity
  • 尝试从组件脚本块使用命名导出 → 查看sfc-named-exports-forbidden
  • 变量更改后模板中未更新 → 查看sfc-script-setup-reactivity

Plugins

插件

  • Debugging why global properties cause naming conflicts → See plugin-global-properties-sparingly
  • Plugin not working or inject returns undefined → See plugin-install-before-mount
  • 调试全局属性导致命名冲突的原因 → 查看plugin-global-properties-sparingly
  • 插件无法工作或inject返回undefined → 查看plugin-install-before-mount

App Configuration

应用配置

  • App configuration methods not working after mount call → See configure-app-before-mount
  • 调用mount后应用配置方法无法工作 → 查看configure-app-before-mount