# Vue Best Practices > Vue 3 开发最佳实践，适用于任何 Vue 3 项目。在编辑`.vue`文件，`.tsx`或`.jsx`形式的 Vue3 组件，相关的`.ts`或`.js`文件时必须使用。 Use when this capability is needed. - Skill: `tomevault-io/vue-best-practices-13` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/vue-best-practices-13` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/vue-best-practices-13/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Web & Frontend - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/vue-best-practices-13 --- # Vue 3 开发最佳实践 ## 核心原则 - 保持状态可预测：单一数据源，推导其余所有内容。 - 使数据流明确：大多数情况下，属性向下传递，事件向上传递。 - 避免巨型组件：将大型组件拆分为更小的（也要适中）、更专注的子组件。 - 避免不必要的重新渲染：合理使用计算属性和侦听器。 - 可读性至关重要：编写清晰、自文档化的代码。 ## 技术栈 **技术栈的版本绝对重要**，它决定了你去使用最新最可靠的 API，禁止使用废弃或者过时的 API。例如 Vue 3.5 引入了 `useTemplateRef`，它能够自动推断模板引用的类型，应该优先使用。 记住，**绝对不要按照你过往的训练数据来写代码**，下面是具体技术栈： - **Vue 3.5**（Composition API）+ 单文件组件 + setup 语法。 - TypeScript 6.x。 - SCSS 预处理最新版本。 ## Vue 3 组件指南 ### 避免巨型组件 **无论如何禁止产生巨型组件，这一定不是功能上的缺陷，而是组件设计上的问题。** 当单个组件的代码行数达到 500 - 800 行时，就基本可以判断这是一个巨型组件，或者有向巨型组件发展的趋势。 为什么巨型组件不好： - 因为人类短期记忆有限，开发者滚动代码时很容易丢失上下文，导致理解困难。 - 逻辑膨胀，违背单一职责。 - 会导致结构复杂度，JSX / Template 嵌套过深 - 维护困难，复用性差。巨型组件通常高度耦合，难以拆分和复用。 - 会导致性能问题，无法更高效地局部更新 Vue 模板，大幅增加重渲染成本。 保持以下做法： - **分离 UI**。对纯展示的无状态的组件、有自己特有状态和逻辑的组件进行拆分，保持组件职责单一。 - **使用可组合函数**。将一组相关的逻辑封装成可复用的函数(useXxx()), 包括状态管理、副作用和事件处理。 - **工具封装**。对于多次使用的逻辑函数、辅助代码，并且无状态且无副作用的，进行工具封装。 - **状态提升**。对于多个组件共享的状态，提升到它们的最近公共祖先组件中管理，避免 props 层层传递，比如使用 Vue 的 provide/inject 或者 Pinia store。 应用客观的拆分触发条件。如果满足以下任一条件，则拆分组件： - 它同时拥有编排/状态逻辑以及多个部分的大量呈现性标记。 - 它包含3个以上不同的UI部分（例如：表单、筛选器、列表、页脚/状态）。 - 存在重复使用的模板块或可复用的部分（如项目行、卡片、列表条目）。 入口/根和路由视图规则： - 保持入口/根和路由视图组件精简：应用外壳/布局、提供者连接和功能组合。 - 当功能包含独立部分时，不要将完整的功能实现放在入口/根/视图组件中。 ### 代码可读性 - **清晰的命名**。变量、函数、组件和文件应该有描述性的名称，准确反映它们的目的和行为。 - **一致的风格**。遵循一致的代码风格和约定。 - **避免过度抽象**。过度抽象会增加理解和调试的难度，保持代码简单直接。 - **使用注释**。在复杂的逻辑或不直观的部分添加注释，但避免过度注释，代码应该尽可能自解释。 ### 保证性能 - **使用异步组件**。对重量级的、不常用的、按需使用的组件使用异步组件来懒加载。 - **避免频繁渲染整个模板**。 禁止高频触发的事件、动画、定时器导致整个模板重新渲染的情况，比如使用鼠标拖拽滑块时只想更新滑块的 UI 状态，却导致整个页面重新渲染，哪怕看起来页面其它部分没有变化，Vue 也会重新执行整个模板的渲染函数，导致性能问题。 - **对列表渲染绑定key**。 - **减少响应式系统开销**。 - 避免什么变量都定义成响应式对象，要根据实际业务需求来判断。 - 对于不需要响应式的属性，使用 `shallowRef` 或 `shallowReactive`。 - **防止内存泄露**。 - 在组件销毁时清理定时器、事件监听器和其他副作用。 - 使用 `onUnmounted`、`onBeforeUnmount`、`onScopeDispose`等生命周期钩子来执行清理逻辑。 --- > Source: [cabinet-fe/ultra-ui](https://github.com/cabinet-fe/ultra-ui) — distributed by [TomeVault](https://tomevault.io).