Vue 3 单文件组件需严格遵循结构顺序、分层规范与命名规则：template→script setup→style scoped；script 内按导入、类型定义、响应式状态、生命周期、方法、暴露内容六区块组织；文件名 PascalCase，props/emits 必须类型化且语义化，样式必须 scoped，通过 ESLint/Prettier/CI 机制强制落地。
团队协作中，Vue 3 单文件组件（.vue）的书写顺序和代码规范不是“写对就行”，而是要让多人能快速定位、安全修改、低风险合入。核心是结构一致 + 语义清晰 + 顺序可预期，不依赖个人经验，靠约定驱动。
一、单文件组件三块顺序固定不可调换
所有 .vue 文件必须严格按以下物理顺序书写，不跳过、不颠倒、不合并：
- <template>：仅包含模板结构，不写逻辑、不放注释块（如“表单区域”这类说明应放在 script 中对应位置）
- <script setup>：必须使用 setup 语法糖；禁止 Options API；无 name 选项（由文件名隐式决定）
- <style scoped>：必须带 scoped；CSS 变量优先用 :root 或 CSS-in-JS 方式管理主题，避免硬编码颜色/尺寸
二、<script setup> 内部代码分层组织
按功能相关性纵向分块，每块用 // —— 区块名 —— 注释标识，区块间空一行：
- // —— 导入 ——：按优先级顺序导入（Vue API → 第三方库 → 项目内 utils/api/enums → store → 组件）
- // —— 类型定义与常量 ——：interface/type/const 定义，不混在逻辑中
- // —— 响应式状态 ——：ref/reactive/computed 集中声明，变量名语义化（如 isSubmitting、formErrors）
- // —— 生命周期与副作用 ——：onMounted、watch、onBeforeUnmount 等统一放这里，避免散落
- // —— 方法与事件处理 ——：函数命名以动词开头（handleSubmit、toggleSidebar），布尔类方法可用 is/can/has 前缀（如 isValidForm）
- // —— 暴露给 template 的内容 ——：仅 return 显式需要的变量和函数，不 return 工具函数或中间状态
三、命名与结构硬性规则
这些不是建议，是 lint 规则应强制拦截的红线：
立即学习“前端免费学习笔记（深入）”；
- 组件文件名：PascalCase，如 UserProfileCard.vue，禁用 kebab-case 或下划线
- Props 声明：必须类型化（defineProps<{...}>()），布尔值 props 必须用 is/has/can 前缀（
isVisible✅，visible❌） - Emits 声明：必须类型化（defineEmits<{...}>()），事件名用 kebab-case（
item-delete），不使用 camelCase - 样式作用域：scoped 是默认要求；穿透需显式写
:deep(.el-input)，禁用 /deep/ 或 ::v-deep - 无冗余代码：删除未使用的 import、未引用的 ref、空的生命周期钩子、注释掉的代码块
四、团队落地关键动作
规范生效靠机制，不靠自觉：
- 在 ESLint + Vue ESLint 插件中启用
vue/multi-word-component-names、vue/require-default-prop等规则，并配置.eslintrc.js全局校验 .vue 结构 - 提交前运行
npm run format（基于 Prettier + eslint-plugin-vue），自动修复缩进、引号、空行等格式问题 - CI 流水线增加
vue-docgen-cli检查组件是否缺失 props 文档注释（@param/@description） - 新成员入职时，提供一份含错误示例和正确示例的对照文档（如 “错误：props 未类型化” vs “正确：defineProps<{name: string}>()”）
