📝 前言

在前端开发中，一个项目的可维护性，很大程度上取决于前期的《工程化规范》。很多团队在项目初期没有定好规矩，随着业务膨胀，components 文件夹变成了深不见底的“垃圾桶”，首屏加载慢如蜗牛，新员工接手时如同在看“天书”。

本文总结了 Vue / uni-app 生态中业界极其成熟的**“约定俗成”潜规则。不仅包含基础的文件命名法则，更引入了现代前端高阶的 UI/Feature 架构解耦与小程序分包策略**。

掌握这套规范，你的代码库也能像瑞士名表一样结构精密、井井有条！

---

🌟 黄金总则（牢记这三句话）

1. 导出 Vue 组件（UI 实体）：一律用大驼峰 PascalCase（如 GoodsCard.vue）。

2. 纯 JS/TS 逻辑文件（工具、接口、状态、混入）：一律用小驼峰 camelCase（如 formatTime.js, useUser.js）。

3. 文件夹、URL 路由、静态资源、分包名：一律用短横线 kebab-case（如 user-profile/）。

---

📂 一、 页面与分包 (Pages & Subpackages) —— 性能优化的生命线

在 uni-app 和微信小程序中，主包大小严格限制在 2MB。如果不做分包，项目根本无法上线。因此，路由目录必须按“主包”和“分包”严格隔离，且必须使用短横线命名法（kebab-case）。

• 📍 规范：文件夹名(kebab-case) / index.vue

• 💡 架构技巧：主包 pages 只放极其核心的页面（如首页、Tabbar 页、登录页）。其他业务模块全部扔进 subpackages（或者叫 pages-xxx）。

✅ 正确示范：

📁 pages/                  # 主包：核心骨架
  ├── 📁 home-index/       # 首页大厅
  │   └── index.vue
  └── 📁 login-auth/       # 登录页
      └── index.vue

📁 subpackages/            # 分包：按业务域划分
  ├── 📁 order-center/     # 订单业务分包
  │   ├── 📁 order-list/
  │   │   └── index.vue
  │   └── 📁 order-detail/
  │       └── index.vue
  └── 📁 user-center/      # 用户中心分包
      └── index.vue

---

🧩 二、 组件解耦：UI 与 Feature (核心架构升级！)

这是现代前端工程化与老旧项目最大的分水岭。不要再把所有组件都塞进一个 components 文件夹了！ 我们必须将组件严格划分为“基础 UI 组件”和“业务特性组件”。

1. 基础积木：UI (Dumb Components)

• 定位：纯视觉、无状态、无业务逻辑。它们只负责“长什么样”，可以通过 props 接收数据，通过 emit 抛出事件。放到任何其他项目里都能直接用。

• 📍 规范：大驼峰 PascalCase.vue，为了防止和内置标签冲突，建议带上前缀（如 Base 或你的项目缩写 Zif）。

✅ 正确示范：

📁 ui/ (或 components/common/)
  ├── BaseButton.vue       # 全局通用按钮
  ├── BaseModal.vue        # 全局通用弹窗
  └── ScrollTray.vue       # 通用横向滑块

2. 业务模块：Feature (Smart Components)

• 定位：包含具体的业务逻辑、会调用后端 API、会读取 Vuex/Pinia 状态。它们通常由多个 UI 组件拼装而成，属于高内聚的业务模块。

• 📍 规范：按业务领域划分文件夹（大驼峰或短横线均可，团队内统一即可），内部包含专属的 Vue 组件。

✅ 正确示范：

📁 features/ (或 modules/)
  ├── 📁 WatchConfigurator/      # 手表定制器业务模块
  │   ├── Watch3DStage.vue       # 3D渲染区组件
  │   └── MaterialPicker.vue     # 材质选择器组件
  └── 📁 CheckoutCart/           # 购物车结算模块
      ├── CartList.vue           # 列表组件
      └── PriceSummary.vue       # 价格计算组件

---

🧬 三、 逻辑复用 (Mixins / Composables / Hooks)

如何处理不同组件里重复的 JS 逻辑（比如下拉刷新、分页加载、表单校验）？ 在 Vue 2 时代我们用 mixins（混入），在 Vue 3 时代我们强烈推荐用 composables（组合式 API Hooks）。

• 📍 规范：小驼峰 camelCase.js。

• 💡 命名技巧：如果是 Vue 3 的 Hook，必须以 use 开头（如 usePagination.js）。如果是 Vue 2 的 Mixin，建议以 Mixin 结尾（如 listRefreshMixin.js）。

✅ 正确示范：

📁 hooks/ (Vue3) 或 📁 mixins/ (Vue2)
  ├── usePagination.js     # 抽离的分页加载逻辑
  ├── useWechatShare.js    # 抽离的微信分享逻辑
  └── uploadMixin.js       # (Vue2做法) 上传文件的混入逻辑

---

🧠 四、 状态管理与网络请求 (Store & API)

将数据流和接口请求与 UI 渲染彻底剥离，按业务域（Domain）划分。

• 📍 规范：小驼峰 camelCase.js

✅ 正确示范：

📁 store/                  # 状态管理 (Vuex / Pinia)
  ├── index.js             # 根实例
  └── 📁 modules/
      ├── user.js          # 用户状态
      └── shoppingCart.js  # 购物车状态

📁 api/                    # 网络请求
  ├── user.js              # login, getUserInfo 接口
  └── order.js             # createOrder 接口

---

🎨 五、 静态资源与常量配置 (Static & Config)

• 静态资源大坑：Windows 对大小写不敏感，Linux 极度敏感！静态资源（图片、CSS）绝对禁止使用大小写混合。

• 📍 规范 (静态资源)：全小写 + 短横线 kebab-case.png。

• 📍 规范 (常量)：文件名小驼峰 camelCase.js，文件内部变量大写 + 下划线 UPPER_SNAKE_CASE。

✅ 正确示范：

📁 static/                 # 图片资源
  ├── logo-dark.png        # ✅ 极度安全
  └── bg-home-header.jpg   # ✅ 极度安全

📁 config/                 # 常量与配置
  ├── envConfig.js         # 环境配置
  └── errorCode.js         # 错误码枚举 (内含: export const TOKEN_EXPIRED = 401;)

---

🏆 终极总结：一张图看懂大型化项目全貌

当你的项目融合了分包机制、UI/Feature 解耦、以及逻辑混入后，它的“完美终极形态”应该长这样：

根目录/
├── 📁 api/                   (小驼峰) -> user.js, order.js
├── 📁 config/                (小驼峰) -> env.js, errorCode.js
├── 📁 features/              (大驼峰) -> 包含业务逻辑的 Smart 组件组合
│   └── 📁 AuthModule/        -> LoginForm.vue, SmsButton.vue
├── 📁 hooks/                 (小驼峰) -> usePagination.js, useShare.js
├── 📁 pages/                 (短横线) -> 主包：home-index/index.vue
├── 📁 static/                (短横线) -> logo-dark.png
├── 📁 store/                 (小驼峰) -> modules/user.js
├── 📁 styles/                (短横线) -> global-vars.scss
├── 📁 subpackages/           (短横线) -> 分包：order-center/index.vue
├── 📁 ui/                    (大驼峰) -> 纯视觉的 Dumb 组件：BaseButton.vue
└── 📁 utils/                 (小驼峰) -> request.js, validate.js

写在最后： “代码是写给人看的，只是顺便让机器执行。” 严格的架构和命名规范，短期看是增加了一点点心智负担，但长期看，它能让你的项目具备无限的扩展性。有了这套底座，无论接手多少复杂的业务，前端大楼都能稳如泰山！

如果你觉得这篇文章对你有启发，欢迎点赞收藏！你遇到过哪些让你崩溃的代码目录？欢迎在评论区吐槽交流。👇