Vue 3 最佳实践、常见陷阱和性能优化。

响应式

• 在脚本中访问 ref() 值时不带 .value → 参见 ref-value-access

• 解构 reactive() 对象，丢失响应性 → 参见 reactive-destructuring

• 为状态选择 ref() 和 reactive() → 参见 prefer-ref-over-reactive

• 访问数组和集合内的 ref → 参见 refs-in-collections-need-value

• 大对象或外部库数据开销 → 参见 shallow-ref-for-performance

• 在模板表达式中使用嵌套 ref → 参见 template-ref-unwrapping-top-level

• 使用 === 运算符比较响应式对象 → 参见 reactivity-proxy-identity-hazard

• 库实例在响应式状态中损坏 → 参见 reactivity-markraw-for-non-reactive

• 期望侦听器对每次状态更改都触发 → 参见 reactivity-same-tick-batching

• 集成外部状态管理库 → 参见 reactivity-external-state-integration

• 追踪意外的重新渲染和状态更新 → 参见 reactivity-debugging-hooks

• 使用 watchEffect 而不是 computed 派生状态 → 参见 reactivity-computed-over-watcheffect-mutations

计算属性

• 计算属性 getter 进行 API 调用或突变 → 参见 computed-no-side-effects

• 突变计算属性值导致意外丢失更改 → 参见 computed-return-value-readonly

• 计算属性未按预期更新 → 参见 computed-conditional-dependencies

• 排序或反转数组破坏原始数据 → 参见 computed-array-mutation

• 昂贵操作在每次渲染时过于频繁地运行 → 参见 computed-vs-methods-caching

• 试图向计算属性传递参数 → 参见 computed-no-parameters

• 复杂条件导致内联类绑定臃肿 → 参见 computed-properties-for-class-logic

侦听器

• 需要侦听响应式对象属性 → 参见 watch-reactive-property-getter

• 大型嵌套数据结构导致性能问题 → 参见 watch-deep-performance

• 异步操作被陈旧数据覆盖 → 参见 watch-async-cleanup

• 在异步回调中创建侦听器 → 参见 watch-async-creation-memory-leak

• await 之后访问的依赖项未被追踪 → 参见 watcheffect-async-dependency-tracking

• 需要在侦听器中访问更新后的 DOM → 参见 watch-flush-timing

• 不确定是使用 watch 还是 watchEffect → 参见 watch-vs-watcheffect

• 重复初始调用和侦听器回调 → 参见 watch-immediate-option

• 无法正确比较新旧值 → 参见 watch-deep-same-object-reference

• 模板 ref 显示为 null 或陈旧 → 参见 watcheffect-flush-post-for-refs

组件

• prop 值被子组件更改 → 参见 props-are-read-only

• 父组件无法在 script setup 中访问子组件 ref 数据 → 参见 component-ref-requires-defineexpose

• 子组件抛出“组件未找到”错误 → 参见 local-components-not-in-descendants

• 点击监听器未在自定义组件上触发 → 参见 click-events-on-components

• HTML 模板解析破坏 Vue 组件语法 → 参见 in-dom-template-parsing-caveats

• 祖父母组件无法监听孙组件发出的事件 → 参见 component-events-dont-bubble

• 由于命名冲突导致渲染错误的组件 → 参见 component-naming-conflicts

• 区分 Vue 组件与原生元素 → 参见 component-naming-pascalcase

• 父组件样式未应用于多根组件 → 参见 multi-root-component-class-attrs

• 递归组件需要引用自身 → 参见 self-referencing-component-name

• 捆绑包包含未使用的组件 → 参见 prefer-local-component-registration

• 通过组件 ref 访问进行紧耦合 → 参见 prefer-props-emit-over-component-refs

Props & Emits

• 布尔 prop 未按预期解析 → 参见 prop-boolean-casting-order

• prop 更改时组合式函数未更新 → 参见 prop-composable-reactivity-loss

• defineProps 中引用的变量导致错误 → 参见 prop-defineprops-scope-limitation

• 解构的 prop 未更新侦听器 → 参见 prop-destructured-watch-getter

• prop 验证需要组件实例数据 → 参见 prop-validation-before-instance

• 组件发出未声明的事件导致警告 → 参见 declare-emits-for-documentation

• defineEmits 在函数或条件内部使用 → 参见 defineEmits-must-be-top-level

• defineEmits 同时具有类型和运行时参数 → 参见 defineEmits-no-runtime-and-type-mixed

• 模板和脚本中的事件名称不一致 → 参见 emit-kebab-case-in-templates

• 事件负载在开发期间需要验证 → 参见 emit-validation-for-complex-payloads

• 原生事件监听器未响应点击 → 参见 native-event-collision-with-emits

• 点击时组件事件触发两次 → 参见 undeclared-emits-double-firing

模板

• 将不受信任的用户内容渲染为 HTML → 参见 v-html-xss-security

• 过滤或有条件地隐藏列表项 → 参见 no-v-if-with-v-for

• 列表项意外消失或交换状态 → 参见 v-for-key-attribute

• 使用语句时出现模板编译错误 → 参见 template-expressions-restrictions

• 动态指令参数无法正常工作 → 参见 dynamic-argument-constraints

• 模板中的函数意外修改数据 → 参见 template-functions-no-side-effects

• v-else 元素总是无条件渲染 → 参见 v-else-must-follow-v-if

• 循环中的子组件显示未定义数据 → 参见 v-for-component-props

• 排序或反转后数组顺序更改 → 参见 v-for-computed-reverse-sort

• 范围迭代出现差一错误 → 参见 v-for-range-starts-at-one

• 过滤或排序列表导致性能问题 → 参见 v-for-use-computed-for-filtering

• "Cannot read property of undefined" 运行时错误 → 参见 v-if-null-check-order

• 在 v-if 和 v-show 之间选择用于条件渲染 → 参见 v-if-vs-v-show-performance

• 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

• 需要在子组件中处理 v-model 修饰符 → 参见 definemodel-hidden-modifier-props

• 对象属性更改未同步到父组件 → 参见 definemodel-object-mutation-no-emit

• 需要在更改后立即使用更新的值 → 参见 definemodel-value-next-tick

• 中文/日文输入的实时搜索/验证损坏 → 参见 v-model-ime-composition

• 数字输入返回空字符串而不是零 → 参见 v-model-number-modifier-behavior

• 将 Vue 2 组件迁移到 Vue 3 → 参见 v-model-vue3-breaking-changes

• 自定义复选框值未在表单中提交 → 参见 checkbox-true-false-value-form-submission

事件 & 修饰符

• 链接多个事件修饰符产生意外结果 → 参见 event-modifier-order-matters

• 需要只处理一次同一事件 → 参见 event-once-modifier-for-single-use

• 键盘快捷键使用非预期的修饰符组合触发 → 参见 exact-modifier-for-precise-shortcuts

• 键盘快捷键不随系统修饰键触发 → 参见 keyup-modifier-timing

• 使用左手鼠标或非标准输入设备 → 参见 mouse-button-modifiers-intent

• 阻止默认浏览器行为和滚动性能在一起 → 参见 no-passive-with-prevent

生命周期

• 生命周期钩子不异步执行 → 参见 lifecycle-hooks-synchronous-registration

• 组件挂载前 DOM 访问失败 → 参见 lifecycle-dom-access-timing

• 未移除事件监听器导致内存泄漏 → 参见 cleanup-side-effects

• SSR 渲染与客户端激活不同 → 参见 lifecycle-ssr-awareness

• 昂贵操作极大地降低性能 → 参见 updated-hook-performance

• 状态更改后 DOM 读取返回陈旧值 → 参见 dom-update-timing-nexttick

插槽

• 在插槽内容中访问子组件数据 → 参见 slot-render-scope-parent-only

• 混合使用具名插槽和作用域插槽 → 参见 slot-named-scoped-explicit-default

• 在原生 HTML 元素上使用 v-slot → 参见 slot-v-slot-on-components-or-templates-only

• 空包装元素不必要地渲染 → 参见 slot-conditional-rendering-with-slots

• 作用域插槽 prop 缺乏 TypeScript 类型安全 → 参见 slot-define-slots-for-typescript

• 渲染没有默认值的空组件插槽 → 参见 slot-fallback-content-default-values

• 包装组件破坏子插槽功能 → 参见 slot-forwarding-to-child-components

• 混淆哪个插槽内容去哪里 → 参见 slot-implicit-default-content

• 期望作用域插槽 prop 中有 name 属性 → 参见 slot-name-reserved-prop

• 在无渲染组件和组合式函数之间选择 → 参见 slot-renderless-components-vs-composables

Provide/Inject

• 提供者更改时注入的值未更新 → 参见 provide-inject-reactivity-not-automatic

• 异步操作后调用 provide 失败且无声息 → 参见 provide-inject-synchronous-setup

• 字符串键在大型应用中冲突 → 参见 provide-inject-symbol-keys

• 追踪提供的值来自何处 → 参见 provide-inject-debugging-challenges

• 多个组件共享相同的默认对象 → 参见 provide-inject-default-value-factory

• 状态突变分散在组件之间 → 参见 provide-inject-mutations-in-provider

• 通过许多组件层传递 props → 参见 avoid-prop-drilling-use-provide-inject

Attrs

• 内部和透传事件处理器都执行 → 参见 attrs-event-listener-merging

• 在 JavaScript 代码中访问连字符属性 → 参见 attrs-hyphenated-property-access

• 使用 watch() 侦听透传属性更改 → 参见 attrs-not-reactive

• 显式属性被透传值覆盖 → 参见 fallthrough-attrs-overwrite-vue3

• 属性应用于包装器中的错误元素 → 参见 inheritattrs-false-for-wrapper-components

组合式函数

• 组合式函数具有影响外部状态的意外副作用 → 参见 composable-avoid-hidden-side-effects

• 在 setup 上下文之外或异步调用组合式函数 → 参见 composable-call-location-restrictions

• 从较小的专注组合式函数构建复杂逻辑 → 参见 composable-composition-pattern

• 不一致的组合式函数名称或解构丢失响应性 → 参见 composable-naming-return-pattern

• 组合式函数有许多可选参数或令人困惑的参数顺序 → 参见 composable-options-object-pattern

• 需要防止不受控制的组合式函数状态突变 → 参见 composable-readonly-state

• 输入更改时组合式函数响应式依赖项未更新 → 参见 composable-tovalue-inside-watcheffect

• 不确定逻辑属于组合式函数还是工具函数 → 参见 composable-vs-utility-functions

组合式 API

• 优化生产包大小和性能 → 参见 composition-api-bundle-size-minification

• 组合式 API 代码变得分散且难以维护 → 参见 composition-api-code-organization

• 修复 mixin 中的命名冲突和不明确的数据来源 → 参见 composition-api-mixins-replacement

• 错误地将函数式模式应用于 Vue 状态 → 参见 composition-api-not-functional-programming

• 逐步迁移大型选项式 API 代码库 → 参见 composition-api-options-api-coexistence

• 异步操作后生命周期钩子静默失败 → 参见 composition-api-script-setup-async-context

• 来自 React，不必要地过度设计 Vue 模式 → 参见 composition-api-vs-react-hooks-differences

• 父组件 ref 无法访问公开的属性 → 参见 define-expose-before-await

指令

• 跨指令钩子存储状态 → 参见 directive-arguments-read-only

• 将自定义指令应用于 Vue 组件 → 参见 directive-avoid-on-components

• 在指令中创建间隔或事件监听器 → 参见 directive-cleanup-in-unmounted

• 简化具有相同行为的指令 → 参见 directive-function-shorthand

• 在 script setup 中使用自定义指令 → 参见 directive-naming-v-prefix

• 在自定义指令和内置指令之间选择 → 参见 directive-prefer-declarative-templating

• 在指令和组件之间决定 → 参见 directive-vs-component-decision

• 将 Vue 2 指令迁移到 Vue 3 → 参见 directive-vue2-migration-hooks

过渡

• 将多个元素或组件包装在过渡中 → 参见 transition-single-element-slot

• 在相同元素类型之间过渡而无动画 → 参见 transition-key-for-same-element

• 使用 JavaScript 动画而不调用 done 回调 → 参见 transition-js-hooks-done-callback

• 使用 TransitionGroup 动画化列表而没有唯一键 → 参见 transition-group-key-requirement

• 抖动的列表动画导致性能问题 → 参见 transition-animate-transform-opacity

• 移动动画在内联列表元素上失败 → 参见 transition-group-flip-inline-elements

• 列表项跳跃而不是平滑动画 → 参见 transition-group-move-animation-position-absolute

• Vue 2 到 Vue 3 过渡布局意外中断 → 参见 transition-group-no-default-wrapper-vue3

• 试图使用 mode 属性对列表动画进行排序 → 参见 transition-group-no-mode-prop

• 为列表项动画创建级联延迟 → 参见 transition-group-staggered-animations

• 过渡期间元素重叠或布局跳跃 → 参见 transition-mode-out-in

• 嵌套过渡动画过早切断 → 参见 transition-nested-duration

• 带有作用域样式的可复用过渡组件中断 → 参见 transition-reusable-scoped-style

• RouterView 过渡在页面加载时意外动画化 → 参见 transition-router-view-appear

• 混合 CSS 过渡和动画导致时间问题 → 参见 transition-type-when-mixed

• 组件清理在快速过渡替换期间未触发 → 参见 transition-unmount-hook-timing

动画

• 需要动画化保留在 DOM 中的元素 → 参见 animation-class-based-technique

• 内容更改时动画未触发 → 参见 animation-key-for-rerender

• 使用用户输入构建交互式动画 → 参见 animation-state-driven-technique

• 动画化列表更改导致明显的滞后 → 参见 animation-transitiongroup-performance

KeepAlive

• 使用 KeepAlive 而没有适当的缓存限制或清理 → 参见 keepalive-memory-management

• KeepAlive include/exclude 属性与缓存组件不匹配 → 参见 keepalive-component-name-requirement

• 需要以编程方式从 KeepAlive 缓存中删除组件 → 参见 keepalive-no-cache-removal-vue3

• 期望新鲜页面数据时用户看到陈旧的缓存内容 → 参见 keepalive-router-fresh-vs-cached

• 子组件在嵌套 Vue Router 路由中挂载两次 → 参见 keepalive-router-nested-double-mount

• 将 KeepAlive 与 Transition 动画结合使用时内存增长 → 参见 keepalive-transition-memory-leak

• 在动态组件之间切换时状态重置 → 参见 dynamic-components-with-keepalive

异步组件

• 设置 Vue Router 路由组件加载 → 参见 async-component-vue-router

• 异步组件选项被父 Suspense 忽略 → 参见 async-component-suspense-control

• 加载组件时网络故障或超时 → 参见 async-component-error-handling

• 改善 SSR 应用的可交互时间 → 参见 async-component-hydration-strategies

• 组件重新激活后模板 ref 未定义 → 参见 async-component-keepalive-ref-issue

• 快速网络上加载微调器闪烁 → 参见 async-component-loading-delay

渲染函数

• 来自 setup 的渲染函数未响应式更新 → 参见 rendering-render-function-return-from-setup

• 同一 vnode 在树中出现多次 → 参见 render-function-vnodes-must-be-unique

• 在没有键的渲染函数中渲染列表 → 参见 render-function-v-for-keys-required

• 在渲染函数中实现 .stop, .prevent → 参见 render-function-event-modifiers

• 在渲染函数中的组件上进行双向绑定 → 参见 render-function-v-model-implementation

• 在渲染函数中为组件使用字符串名称 → 参见 rendering-resolve-component-for-string-names

• 访问 vnode 内部，如 el 或 shapeFlag → 参见 render-function-avoid-internal-vnode-properties

• 创建简单的无状态展示组件 → 参见 render-function-functional-components

• 在渲染函数中应用自定义指令 → 参见 render-function-custom-directives

• 来自侦听器或深度侦听器的过多重新渲染 → 参见 rendering-excessive-rerenders-watch-vs-computed

• 选择渲染函数而非模板 → 参见 rendering-prefer-templates-over-render-functions

• 将 Vue 2 渲染函数迁移到 Vue 3 → 参见 rendering-render-function-h-import-vue3

• 错误地将插槽内容传递给 h() → 参见 rendering-render-function-slots-as-functions

• 理解 Vue 的 vdom 优化块 → 参见 rendering-understand-vdom-block-structure

Teleport

• 在 DOM 中未找到 Teleport 目标元素 → 参见 teleport-target-must-exist

• 传送的内容破坏 SSR 激活 → 参见 teleport-ssr-hydration

• 模态框因父级 CSS 变换而中断 → 参见 teleport-css-positioning-issues

• 内容在移动设备上需要不同的布局 → 参见 teleport-disabled-for-responsive

• 不确定 props/events 是否通过 teleport 工作 → 参见 teleport-logical-hierarchy-preserved

• 多个模态框针对同一容器 → 参见 teleport-multiple-to-same-target

• 作用域样式未应用于传送的内容 → 参见 teleport-scoped-styles-limitation

Suspense

• 需要处理来自 Suspense 组件的异步错误 → 参见 suspense-no-builtin-error-handling

• 想要以编程方式追踪 Suspense 加载状态 → 参见 suspense-events-for-state-tracking

• 规划生产应用中的 Suspense 使用 → 参见 suspense-experimental-api-stability

• 内容更改时未显示回退 → 参见 suspense-fallback-not-immediate-on-revert

• 将 Suspense 组件嵌套在一起 → 参见 suspense-nested-suspensible-prop

• 将 Suspense 与 Router、Transition、KeepAlive 结合使用 → 参见 suspense-nesting-order-with-router

• 嵌套异步组件未显示加载指示器 → 参见 suspense-revert-only-on-root-change

• 单个 Suspense 中的多个异步组件 → 参见 suspense-single-child-requirement

• 在服务器端渲染中使用 Suspense → 参见 suspense-ssr-hydration-issues

TypeScript

• 在组合式 API 组件中使用 TypeScript 声明 props → 参见 ts-defineprops-type-based-declaration

• 为可变 prop 类型提供默认值 → 参见 ts-withdefaults-mutable-factory-function

• 使用 ref 解包关注点类型化响应式状态 → 参见 ts-reactive-no-generic-argument

• 组件挂载后访问 DOM 元素 → 参见 ts-template-ref-null-handling

• 类型化子 Vue 组件的 ref → 参见 ts-component-ref-typeof-instancetype

• 使用具有 TypeScript 支持的自定义指令 → 参见 ts-custom-directive-type-augmentation

• 使用完全类型安全声明组件事件 → 参见 ts-defineemits-type-based-syntax

• 在 TypeScript 中处理可选布尔 props → 参见 ts-defineprops-boolean-default-false

• 在 defineProps 中安全使用导入的类型 → 参见 ts-defineprops-imported-types-limitations

• 使用严格 TypeScript 检查处理 DOM 事件 → 参见 ts-event-handler-explicit-typing

• 在具有类型安全的组件之间共享数据 → 参见 ts-provide-inject-injection-key

• 在响应式状态中存储 Vue 组件 → 参见 ts-shallowref-for-dynamic-components

• 在 Vue 模板中使用联合类型 → 参见 ts-template-type-casting

SSR

• 用户数据在服务器请求之间泄漏 → 参见 state-ssr-cross-request-pollution

• HTML 在服务器和客户端渲染之间不同 → 参见 ssr-hydration-mismatch-causes

• 代码在服务器和浏览器环境中运行 → 参见 ssr-platform-specific-apis

• 自定义指令未显示在服务器渲染的 HTML 上 → 参见 ssr-custom-directive-getssrprops

性能

• 状态更改期间许多列表项不必要地重新渲染 → 参见 perf-props-stability-update-optimization

• 渲染成百上千的项目导致 DOM 性能问题 → 参见 perf-virtualize-large-lists

• 静态内容在每次父组件更新时重新评估 → 参见 perf-v-once-v-memo-directives

• 列表性能因深度嵌套组件结构而下降 → 参见 perf-avoid-component-abstraction-in-lists

• 返回对象的计算属性意外触发副作用 → 参见 perf-computed-object-stability

• 页面加载指标受客户端 JavaScript 执行延迟影响 → 参见 perf-ssr-ssg-for-page-load

SFC (单文件组件)

• 试图从组件脚本块使用命名导出 → 参见 sfc-named-exports-forbidden

• 启动具有构建设置的 Vue 项目 → 参见 sfc-recommended-for-build-projects

• 使用作用域 CSS 为子组件元素设置样式 → 参见 sfc-scoped-css-child-component-styling

• 为使用 v-html 动态添加的内容设置样式 → 参见 sfc-scoped-css-dynamic-content

• 优化作用域 CSS 选择器性能 → 参见 sfc-scoped-css-performance

• 为通过组件插槽传递的内容设置样式 → 参见 sfc-scoped-css-slot-content

• 更改后变量在模板中未更新 → 参见 sfc-script-setup-reactivity

• 组织组件模板、逻辑和样式 → 参见 sfc-separation-of-concerns-colocate

• 使用属性名称绑定内联样式 → 参见 style-binding-camelcase

• 使用字符串连接构建 Tailwind 类 → 参见 tailwind-dynamic-class-generation

插件

• 调试全局属性导致命名冲突的原因 → 参见 plugin-global-properties-sparingly

• 插件不工作或 inject 返回 undefined → 参见 plugin-install-before-mount

• 全局属性在 setup 函数中不可用 → 参见 plugin-prefer-provide-inject-over-global-properties

• 从头开始创建一个新的 Vue 插件 → 参见 plugin-structure-install-method

• 防止多个插件之间的冲突 → 参见 plugin-symbol-injection-keys

• 全局属性缺少 TypeScript 自动完成支持 → 参见 plugin-typescript-type-augmentation

应用配置

• mount 调用后应用配置方法不工作 → 参见 configure-app-before-mount

• 需要在 mount 后链式调用应用配置方法 → 参见 mount-return-value

• Vue 仅控制特定页面部分 → 参见 multiple-app-instances

• 将动态组件注册迁移到 Vite → 参见 dynamic-component-registration-vite