现代前端项目目录结构指南：构建清晰可维护的代码架构一个清晰的目录结构是项目可维护性的基石。本文将介绍一种结合了 Next

好的，以下是一篇关于现代 React 项目目录结构设计的文章：

现代 React 项目目录结构设计指南

在大型 React 项目中，合理的目录结构是维护性的基石。一个优秀的架构应该能够随着项目的发展而优雅地扩展，而不是成为开发的绊脚石。

核心目录结构

src/
├── app/
│   ├── (home)/              # 首页路由组
│   │   ├── page.tsx        # 首页组件
│   │   └── components/     # 首页专用组件
│   │       ├── HeroSection/
│   │       └── FeatureCard/
│   ├── (dashboard)/        # 仪表板路由组  
│   │   ├── page.tsx
│   │   └── components/
│   └── layout.tsx
├── components/
│   ├── domains/            # 业务领域组件
│   │   ├── wallet/        # 钱包领域
│   │   ├── trading/       # 交易领域
│   │   └── governance/    # 治理领域
│   ├── ui/                # 基础UI组件
│   │   ├── Button/
│   │   ├── Input/
│   │   └── Modal/
│   └── shared/            # 跨领域共享组件
└── lib/
    ├── utils/             # 工具函数
    └── types/             # 类型定义

各目录职责解析

1. 路由组：`app/(home)/`

作用：使用括号语法创建路由组，实现物理文件分组而不影响 URL 结构
包含：page.tsx（页面组件） + components/（页面专用组件）
优势：相关文件高度内聚，维护时无需在多个目录间跳转

2. 领域组件：`components/domains/`

组织原则：按业务领域而非技术角色划分
示例：
- domains/wallet/ - 所有钱包相关功能
- domains/trading/ - 所有交易相关功能
- domains/governance/ - 所有治理相关功能
价值：业务功能集中管理，团队协作边界清晰

3. UI 组件：`components/ui/`

特点：纯展示组件，不含业务逻辑
示例：按钮、输入框、弹窗等基础组件
要求：可跨项目复用，接口简单稳定

组件目录的演进设计

每个组件都应该是独立的目录，这种设计为未来的复杂化提供了充分的扩展空间：

场景1：组件需要拆分子组件

// 简单组件演进为复合组件
ComponentA/
├── ComponentA.tsx        # 主组件
├── SubComponentB.tsx     # 子组件
├── SubComponentC.tsx     # 子组件
└── index.ts             # 对外接口不变

// 使用方完全感知不到内部变化
import ComponentA from './ComponentA'; // 导入方式保持不变

场景2：组件需要导出工具函数

// 增加业务逻辑封装
ComponentA/
├── ComponentA.tsx
├── hooks/
│   └── useComponentLogic.ts  # 自定义Hook
└── index.ts                  # 统一导出接口

场景3：组件需要类型定义

// 增加类型系统支持
ComponentA/
├── ComponentA.tsx
├── types.ts                  # 类型定义
└── index.ts                  # 导出组件和类型

`index.ts` 的战略价值

index.ts 文件充当组件的"前台接待"，它的核心价值在于：

封装内部结构：对外隐藏实现细节，提供稳定接口
统一导出管理：集中管理组件的所有导出项
简化导入路径：让使用方享受简洁的导入体验

没有 index.ts 的痛点：

// 当组件变复杂后，使用方被迫要：
import ComponentA from './ComponentA/ComponentA';
import { useComponentLogic } from './ComponentA/hooks/useComponentLogic'; 
import type { ComponentType } from './ComponentA/types';

// 路径冗长且需要记忆多个导入路径
// 内部文件重组会导致所有导入都需要修改

架构设计哲学

这种目录结构体现了几个重要的软件设计原则：

高内聚低耦合：相关功能集中，模块间依赖清晰
开闭原则：对扩展开放，对修改关闭
单一职责：每个目录和组件都有明确的职责边界
渐进式复杂：从简单开始，按需演进，避免过度设计

总结

一个优秀的目录结构应该：

✅ 易于开发：快速找到相关文件
✅ 易于维护：修改影响范围可控
✅ 易于扩展：支持功能自然生长
✅ 易于协作：团队分工清晰明确

通过 app/(routes)/、components/domains/、components/ui/ 的分层，配合组件目录的 index.ts 封装，我们构建了一个既满足当前需求，又为未来演进留足空间的健壮架构。

现代前端项目目录结构指南：构建清晰可维护的代码架构