人人都会AI编程

19.3 组件命名、文件命名、目录结构规范

更新时间：2026-07-09

规范不是教条，而是团队协作的“默认共识”。当所有人都按同一套规则行事时，找文件、读代码、做 Code Review 的成本会大幅降低。以下规范基于 Vue 官方风格指南和社区沉淀的最佳实践，适合中大型项目。

组件命名：语义化 + 层级化

1. 组件名必须由多个单词组成
避免与现有以及未来的 HTML 元素产生冲突。因为所有 HTML 元素都是单个单词（如 <div>、<img>）。

❌ 错误
<User />、<Card />
✅ 正确
<UserProfile />、<BaseCard />

2. 基础组件以特定前缀开头
基础组件（即通用的、不含业务逻辑的 UI 组件，如按钮、输入框、弹窗）统一使用 Base、App 或 V 作为前缀。

BaseButton.vue
BaseInput.vue
BaseModal.vue

这样在模板中一眼就能识别出哪些是基础设施，哪些是业务组件。

3. 单文件父子组件按层级嵌套命名
如果一个组件只在某个父组件内使用，用父组件名作为前缀。

UserManagement.vue              // 父组件
UserManagementList.vue          // 子组件：用户列表
UserManagementListItem.vue      // 子子组件：列表项
UserManagementFilter.vue        // 子组件：筛选器

4. 按业务域命名
与路由、功能模块相关联的组件，以它们所负责的业务领域开头，便于按功能快速定位。

ProductDetail.vue
ProductDetailSpecs.vue
OrderStatusBadge.vue

5. 模板中使用 PascalCase（大驼峰）
在模板中引用组件时，推荐使用 PascalCase，这样能明确区分组件和原生 HTML 标签。

<template>
  <BaseButton />
  <UserProfile />
</template>

即使使用 kebab-case（如 <base-button />）也可以，但 PascalCase 更利于 IDE 识别和重构。

6. 组件名应该完整，不要过度缩写
组件名应描述其功能，不要害怕名字长。清晰的命名比简短的谜语更有价值。

❌ 模糊
Btn、Dlg、Tbl
✅ 清晰
Button、Dialog、DataTable

文件命名：一致性比规则本身更重要

1. Vue 单文件组件使用 PascalCase 命名
文件系统和版本控制都区分大小写，PascalCase 可以移植性最好，也符合大多数框架的惯例。

components/
  BaseButton.vue
  UserProfile.vue

除非项目特意统一为 kebab-case（如某些老旧系统），否则统一 PascalCase。

2. 组合式函数（Hooks）使用 camelCase，并以 use 开头
这是 Vue 3 社区的约定，便于一眼识别函数的职责。

composables/
  useAuth.ts
  useFetch.ts
  usePagination.ts

3. 工具函数、常量、类型定义文件使用 camelCase 或特定后缀

utils/
  formatDate.ts
  validateEmail.ts
constants/
  apiRoutes.ts
  statusCodes.ts
types/
  product.ts
  order.ts

4. 目录名统一使用 kebab-case 或小写单数名词
这是多数构建工具和操作系统的友好选择。

❌ 不推荐
UserProfile/、User-Management/
✅ 推荐
components/、views/、user-manage/ 或 user/（视含义而定）

5. 一个文件只包含一个组件/功能
除了极少数紧密耦合的私有子组件（如在一个文件中定义 ListItem），不把多个独立组件写在一个 .vue 文件中。也避免把工具函数、状态管理、接口调用混杂在一起。

目录结构：分层清晰，职责单一

一个典型的中大型 Vue 3 + Vite 项目目录结构如下：

src/
├── assets/             # 静态资源（图片、字体、全局样式等）
├── components/         # 全局通用组件
│   ├── base/           # 基础组件（BaseButton, BaseInput...）
│   └── business/       # 业务通用组件（UserAvatar, ProductCard...）
├── composables/        # 组合式函数（Hooks）
├── layouts/            # 页面布局组件（默认布局、侧边栏布局等）
├── router/             # 路由配置
├── stores/             # Pinia 状态管理
├── utils/              # 纯工具函数
├── views/              # 页面级组件（对应路由）
│   ├── user/           # 用户相关页面
│   └── product/        # 产品相关页面
├── App.vue
└── main.ts

核心原则：

  • components/ 存放可复用的全局组件，并按通用性进一步分区（base/、business/）。
  • views/ 存放路由级别的页面组件，通常按业务模块划分子目录，每个页面组件组合 components/ 中的子组件。
  • composables/ 存放逻辑抽象，复用状态和副作用，不包含任何 UI 标记。
  • stores/ 按业务域拆分成多个 Store 文件，而不是一个巨大的 index.js。

结构演进建议：

  • 项目初期不必过度设计目录，可以先有 components/、views/ 和 router/。
  • 当某一类文件数量超过 5~7 个时，再拆分子目录（如 components/base/）。
  • 跨项目的公共模块，考虑抽取为独立 npm 包或放在 packages/ 下（monorepo 场景）。

规范的最终目的，是让任何团队成员打开项目时都能快速回答三个问题：
这个文件在哪里？这个组件叫什么？这个逻辑放在哪？