vue-best-practices

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
• 复杂条件导致内联 class 绑定臃肿 → 参见 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 回调重复执行 → 参见 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

• Boolean prop 未按预期解析 → 参见 prop-boolean-casting-order
• prop 变化时 composable 未更新 → 参见 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

模板引用

• 元素有条件地隐藏时，引用变为 null → 请参阅 template-ref-null-with-v-if
• 循环中的引用数组索引与数据数组不匹配 → 请参阅 template-ref-v-for-order
• 重构模板引用名称后，代码会悄无声息地出错 → 请参阅 use-template-ref-vue35

表单与 v-model

• 使用 v-model 时，初始表单值未显示 → 请参阅 v-model-ignores-html-attributes
• textarea 内容变化未更新引用 → 请参阅 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
• 作用域插槽的属性缺少 TypeScript 类型安全保障 → 请参阅 slot-define-slots-for-typescript
• 未提供默认内容时渲染空的组件插槽 → 请参阅 slot-fallback-content-default-values
• 包装组件导致子组件插槽功能失效 → 请参阅 slot-forwarding-to-child-components
• 不清楚插槽内容会放在哪里 → 请参阅 slot-implicit-default-content
• 预期作用域插槽属性中会有 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

Composables

• Composable 产生意料之外的副作用，影响外部状态 → 参见 composable-avoid-hidden-side-effects
• 在 setup 上下文之外或异步调用 Composable → 参见 composable-call-location-restrictions
• 通过更小、更专注的 Composable 构建复杂逻辑 → 参见 composable-composition-pattern
• Composable 命名不一致，或解构导致响应性丢失 → 参见 composable-naming-return-pattern
• Composable 有许多可选参数，或参数顺序令人困惑 → 参见 composable-options-object-pattern
• 需要防止 Composable 状态被不受控地修改 → 参见 composable-readonly-state
• 输入变化时，Composable 的响应式依赖未更新 → 参见 composable-tovalue-inside-watcheffect
• 不确定逻辑应该放在 Composable 还是工具函数中 → 参见 composable-vs-utility-functions

Composition API

• 优化生产环境构建包大小和性能 → 参见 composition-api-bundle-size-minification
• Composition API 代码变得分散且难以维护 → 参见 composition-api-code-organization
• 解决 mixin 中的命名冲突和数据来源不明问题 → 参见 composition-api-mixins-replacement
• 将函数式模式错误地应用于 Vue 状态 → 参见 composition-api-not-functional-programming
• 逐步迁移大型 Options 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

Directives

• 在指令钩子之间保存状态 → 参见 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 为列表添加动画，但未设置唯一 key → 参见 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
• 在渲染函数中渲染列表时未设置 key → 参见 render-function-v-for-keys-required
• 在渲染函数中实现 .stop、.prevent → 参见 render-function-event-modifiers
• 在渲染函数中的组件上实现双向绑定 → 参见 render-function-v-model-implementation
• 在渲染函数中使用字符串名称表示组件 → 参见 rendering-resolve-component-for-string-names
• 访问 el 或 shapeFlag 等 vnode 内部属性 → 参见 render-function-avoid-internal-vnode-properties
• 创建简单的无状态展示组件 → 参见 render-function-functional-components
• 在渲染函数中应用自定义指令 → 参见 render-function-custom-directives
• watcher 或深度 watcher 导致过度重新渲染 → 参见 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
• Teleport 内容导致 SSR 水合失败 → 参见 teleport-ssr-hydration
• 父级 CSS transform 导致模态框异常 → 参见 teleport-css-positioning-issues
• 移动设备上需要使用不同的内容布局 → 参见 teleport-disabled-for-responsive
• 不确定 props/events 是否能通过 Teleport 正常工作 → 参见 teleport-logical-hierarchy-preserved
• 多个模态框指向同一个容器 → 参见 teleport-multiple-to-same-target
• 作用域样式未应用于 Teleport 内容 → 参见 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 中处理可选的布尔型 prop → 请参阅 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