项目目录结构

工程化规范 项目目录结构

前端项目随着功能迭代和团队协作的深入，合理的目录结构设计直接影响开发效率和维护成本。清晰的目录划分能快速定位代码，统一的命名规范减少沟通成本，模块化的组织方式提升组件复用率。

基础目录结构设计原则

按功能划分优于按文件类型划分。传统做法将相同类型文件放在一起（如所有组件在components/），但随着项目增长会导致目录膨胀。现代前端工程更推荐按业务模块组织：

src/
├── modules/
│   ├── user/
│   │   ├── components/  # 用户模块专属组件
│   │   ├── hooks/       # 模块自定义hooks
│   │   ├── types/       # 模块类型定义
│   │   └── index.ts     # 模块出口文件
│   └── product/
├── core/                # 核心基础设施
│   ├── http/            # 网络请求封装
│   ├── router/          # 路由配置
│   └── store/           # 状态管理
└── shared/              # 全站共享资源
    ├── components/      # 通用基础组件
    ├── utils/           # 工具函数库
    └── styles/          # 全局样式

命名一致性要求目录使用全小写短横线连接（kebab-case），Vue组件使用PascalCase，React组件文件与导出名称保持一致：

// React组件规范示例
// 文件路径：modules/user/components/UserProfileCard.tsx
export default function UserProfileCard() { ... }

// Vue组件规范示例
// 文件路径：modules/user/components/UserProfileCard.vue
<script setup>
defineOptions({ name: 'UserProfileCard' })
</script>

进阶目录规划策略

动态加载目录需要特殊标记。在Next.js或Nuxt等框架中，约定式路由目录通常通过前缀区分：

pages/
├── _protected/         # 需要鉴权的页面
│   └── dashboard.vue
├── _public/            # 公开访问页面
│   └── login.vue
└── api/                # API路由
    └── users.ts

配置分离原则要求将环境相关、构建配置等文件集中管理：

config/
├── webpack/            # 分环境webpack配置
│   ├── common.js
│   ├── dev.js
│   └── prod.js
├── babel.config.js
└── env/                # 环境变量
    ├── .env.development
    └── .env.production

类型系统集成方案

TypeScript项目需要特别设计类型定义存放位置。推荐两种模式：

1. 就近声明：类型与实现文件同目录

modules/
└── order/
    ├── types/
    │   ├── order.d.ts  # 基础类型
    │   └── api.d.ts    # API响应类型
    └── api.ts          # 引用同级类型

2. 全局类型：通过types目录集中管理

// types/global.d.ts示例
declare module '*.vue' {
  import type { DefineComponent } from 'vue'
  const component: DefineComponent
  export default component
}

// types/modules/user.d.ts
interface UserProfile {
  id: string
  avatar: string
}

静态资源管理规范

多媒体资源建议按使用场景分类存放，配合构建工具实现优化：

assets/
├── fonts/              # 字体文件
├── images/             # 通用图片
│   ├── backgrounds/
│   └── icons/
└── modules/            # 模块专属资源
    └── product/
        └── previews/

Webpack配置示例实现自动压缩：

// webpack.config.js
module.exports = {
  module: {
    rules: [
      {
        test: /\.(png|jpe?g|webp)$/i,
        type: 'asset',
        parser: { dataUrlCondition: { maxSize: 8 * 1024 } },
        use: ['image-webpack-loader'] 
      }
    ]
  }
}

测试文件组织方式

测试文件与实现代码的对应关系常见三种模式：

1. __tests__目录：React社区常用

components/
├── Button/
│   ├── index.tsx
│   └── __tests__/
│       ├── unit.test.ts
│       └── snapshot.test.ts

2. 同级.test.js文件：Vue生态常见

stores/
├── userStore.ts
└── userStore.spec.ts

3. 集中测试目录：适合E2E测试

tests/
├── e2e/
│   └── checkout.cy.ts
└── unit/
    └── utils/
        └── dateFormatter.test.ts

文档配套实践

项目文档应当与代码同步更新，推荐使用目录级README：

src/
├── components/
│   └── README.md       # 组件开发规范
├── ADR/                # 架构决策记录
│   └── 001-api-design.md
└── docs/
    ├── style-guide.md  # 样式编写指南
    └── api.md          # 接口文档

Markdown文档示例：

## 按钮组件规范

```jsx
// 基础用法
<Button variant="primary">提交</Button>
```

| 参数       | 类型     | 默认值    |
|------------|----------|-----------|
| `variant`  | `string` | `'default'` |

多仓库管理方案

Monorepo项目需要调整目录结构，以pnpm workspace为例：

packages/
├── web-app/            # 主应用
│   └── package.json
├── mobile-app/         # 移动端
│   └── package.json
└── shared/             # 共享包
    ├── ui-kit/         # 组件库
    └── utils/          # 工具库

配置workspace的package.json：

{
  "private": true,
  "workspaces": ["packages/*"],
  "scripts": {
    "build": "pnpm -r run build"
  }
}

构建产物目录设计

输出目录应包含版本控制和哈希策略：

dist/                   # 构建输出根目录
├── v1.0.0/             # 版本化目录
│   ├── assets/
│   │   ├── js/
│   │   │   └── main.a1b2c3.js
│   │   └── css/
│   │       └── style.x4y5z6.css
│   └── index.html
└── latest/             # 最新版本软链

Nginx配置示例实现缓存优化：

location /assets {
  expires 1y;
  add_header Cache-Control "public";
  access_log off;
}