你是否曾经接过别人的 React 项目，结果面对一堆杂乱无章的文件感到不知所措？或者，当你的项目规模从几个组件扩展到数百个文件时，你是否发现仅仅在寻找一个文件就要花上几分钟？相信我，我们都经历过这种痛苦。
其实，80% 的开发时间都花在阅读和梳理现有代码上，而不是编写新代码。
拥有一个规划良好的文件夹结构，对于代码的可读性、可扩展性和可维护性至关重要。清晰的结构就像是一张精确的地图，它能帮助我们有效地管理代码、配置、模块和其他资源。在 2026 年，随着 AI 辅助编程的普及，这种结构化的思维不仅是为了人类协作，更是为了让 AI 代理（Agents）能更好地理解我们的代码库。
在这篇文章中，我们将深入探讨 React 项目的文件夹结构，学习如何通过结合传统工程化与现代 AI 工作流的最佳实践来组织项目，从而让开发体验变得更加流畅和愉快。
前置准备
在深入探讨之前，为了让你能更好地理解接下来的内容，请确保你已经具备以下基础：
- React 基础：你需要对 React 的组件、Props 和 State 有基本的了解。
- NPM 工具：熟悉 npm 或 pnpm/yarn 的基本命令，因为我们将使用它来管理依赖。
- 开发环境：你需要安装好代码编辑器（如 VS Code 或 Cursor）以及 Node.js。
2026 年的工程化选择：Vite 还是 CRA？
在我们谈论文件夹结构之前，让我们先聊聊脚手架。虽然 create-react-app (CRA) 曾经是标准，但在 2026 年，它已经显得有些过时了。在现代企业级开发中，我们更倾向于使用 Vite 或 Next.js。为什么？因为构建速度直接影响开发体验。
让我们思考一下这个场景：当你启动一个包含数千个文件的大型项目时，CRA 可能需要等待几分钟，而 Vite 只需要几毫秒。这种差异是巨大的。在接下来的示例中，我们将基于 Vite 的项目结构进行展开，因为它更符合现代标准，且文件夹结构与 CRA 类似，但配置更加灵活。
进阶之路：改进后的企业级文件夹结构
随着项目功能的增加，仅仅将文件分为 INLINECODE21607282 和 INLINECODEd6297b18 是不够的。为了以更简洁、更模块化的方式管理项目，我们需要引入更细化的分类。
这就是我们推荐的2026 年改进型文件夹结构，它能帮助你轻松管理大型应用，并且对 AI 友好。
我们将重点添加以下文件夹，让代码职责更加分明：
- Features/Modules Folder (功能模块文件夹)
- Shared/Common Folder (共享组件文件夹)
- Hooks Folder (自定义钩子文件夹)
- Services/API Folder (服务层/接口文件夹)
- Utils/Helpers Folder (工具函数文件夹)
- Store Folder (全局状态文件夹)
- Assets Folder (静态资源文件夹)
核心架构：Feature-Based（基于功能） vs Type-Based（基于类型）
过去，我们习惯将所有组件放在 INLINECODEb0e74152 文件夹，所有 Hooks 放在 INLINECODE121cceb1 文件夹。这叫做“基于类型”的分类。但在大型项目中，这种方式往往会导致修改一个功能时，需要在十个不同的文件夹间跳转。
最佳实践转变：在 2026 年，我们强烈建议采用 “基于功能” 的结构。我们将相关的组件、Hooks、服务接口和样式放在同一个文件夹下。
#### 一个真实的电商模块示例
让我们来看一个实际的例子。假设我们要开发一个“用户资料”功能。按照新的理念，我们的结构应该是这样的：
src/features/user-profile/
├── components/ // 仅属于该功能的组件
│ ├── UserProfileHeader.jsx
│ └── OrderHistory.jsx
├── hooks/ // 仅属于该功能的逻辑
│ └── useUserOrders.js
├── services/ // 仅属于该功能的 API 调用
│ └── userApi.js
├── types/ // TypeScript 类型定义（如果是 JS 项目则是 constants）
│ └── userTypes.js
├── index.jsx // 入口文件
└── userProfileSlice.jsx // 状态管理 slice
这样做的好处是显而易见的：高内聚。当这个模块废弃时，我们只需要删除一个文件夹，而不会在项目中留下到处引用的“僵尸代码”。
Shared/Common Folder (共享组件文件夹)
当然，不是所有东西都应该按功能拆分。对于像 INLINECODE22a4cb5d、INLINECODE46f5badd、INLINECODE49e1ed1b 这样通用的 UI 组件，我们仍然需要一个 INLINECODEe6944330 或 components 文件夹。
在这里，我们建议引入 原子设计 的理念。我们将共享组件细分为：
- atoms (原子): 最基本的单位，如 Button, Icon, Input。
- molecules (分子): 由原子组成，如 SearchBar (Input + Icon)。
- organisms (有机体): 复杂的组合，如 Navbar, Footer。
代码示例：生产级 Button 组件
在这个例子中，我们不仅要写代码，还要考虑到可复用性和可访问性 (a11y)。
// src/shared/components/atoms/Button/Button.jsx
import React from ‘react‘;
import PropTypes from ‘prop-types‘;
import { VariantStyles, SizeStyles } from ‘./buttonStyles‘;
/**
* 通用按钮组件
* 支持多种变体、尺寸和禁用状态，符合 WAI-ARIA 标准。
*/
const Button = ({
children,
variant = ‘primary‘,
size = ‘md‘,
isLoading = false,
disabled,
onClick,
...props
}) => {
// 合并禁用逻辑：加载中或显式禁用时按钮不可点
const isDisabled = disabled || isLoading;
const baseClasses = "rounded font-medium transition-colors duration-200 focus:outline-none focus:ring-2 focus:ring-offset-2";
const variantClass = VariantStyles[variant] || VariantStyles.primary;
const sizeClass = SizeStyles[size] || SizeStyles.md;
return (
);
};
// PropTypes 是 2026 年依然重要的文档化手段（即使有了 TypeScript）
Button.propTypes = {
children: PropTypes.node.isRequired,
variant: PropTypes.oneOf([‘primary‘, ‘secondary‘, ‘danger‘, ‘ghost‘]),
size: PropTypes.oneOf([‘sm‘, ‘md‘, ‘lg‘]),
isLoading: PropTypes.bool,
onClick: PropTypes.func,
};
export default Button;
Hooks Folder (自定义钩子文件夹)
虽然 React 提供了内置的 Hooks，但在实际开发中，我们经常需要复用特定的状态逻辑。在 2026 年，我们不仅要复用逻辑，还要关注服务端状态与客户端状态的区别。
我们建议将 Hooks 分为两类：
- UI Hooks: 处理交互逻辑，如 INLINECODE21c0ff31, INLINECODEfea0497d,
useLocalStorage。 - Data Hooks: 封装 API 调用，配合 TanStack Query (React Query) 使用。
代码示例：健壮的 useFetch Hook
你可能会遇到这样的情况：你需要处理加载状态、错误状态以及数据重试逻辑。如果每个组件都写一遍 INLINECODEc3c90c18 和 INLINECODE01c82232，代码会变得非常臃肿。我们可以通过以下方式解决这个问题。
// src/shared/hooks/useFetch.js
import { useState, useEffect, useCallback } from ‘react‘;
/**
* 封装通用的 Fetch 逻辑
* 注意：在生产环境中，我们通常推荐直接使用 React Query 的 useQuery，
* 但这个 Hook 展示了底层逻辑的封装思想。
*/
const useFetch = (url, options = {}) => {
const [data, setData] = useState(null);
const [loading, setLoading] = useState(true);
const [error, setError] = useState(null);
const fetchData = useCallback(async () => {
setLoading(true);
setError(null);
try {
const response = await fetch(url, options);
if (!response.ok) {
throw new Error(`HTTP error: ${response.status}`);
}
const json = await response.json();
setData(json);
} catch (err) {
setError(err.message);
// 在生产环境中，这里应该上报错误到 Sentry 或其他监控平台
console.error("Fetch error:", err);
} finally {
setLoading(false);
}
}, [url, options]);
useEffect(() => {
fetchData();
}, [fetchData]);
return { data, loading, error, refetch: fetchData };
};
export default useFetch;
Services/API Folder (服务文件夹)
保持代码纯净的一个关键原则是关注点分离。组件不应该直接写复杂的 API 请求逻辑。在这个目录中，你将找到负责处理 API 调用、数据转换和与后端交互的文件。
在现代开发中，我们会为每个实体（如 User, Product）创建一个 Service 文件。
代码示例：结构化的 API 服务
// src/services/api/userService.js
import axios from ‘axios‘;
// 创建 axios 实例以便于统一配置（如 baseURL, timeout, interceptors）
const apiClient = axios.create({
baseURL: process.env.REACT_APP_API_BASE_URL || ‘/api‘,
timeout: 5000,
headers: {
‘Content-Type‘: ‘application/json‘,
}
});
// 请求拦截器：自动附加 Token
apiClient.interceptors.request.use((config) => {
const token = localStorage.getItem(‘auth_token‘);
if (token) {
config.headers.Authorization = `Bearer ${token}`;
}
return config;
}, (error) => {
return Promise.reject(error);
});
// 用户相关的 API 方法
export const userService = {
/**
* 获取用户列表
* @param {number} page 页码
* @param {number} limit 每页数量
*/
getUsers: async (page = 1, limit = 10) => {
const response = await apiClient.get(‘/users‘, { params: { page, limit } });
return response.data; // 假设后端返回 { data: [], total: 100 }
},
/**
* 根据 ID 获取单个用户
* @param {string|number} id
*/
getUserById: async (id) => {
const response = await apiClient.get(`/users/${id}`);
return response.data;
},
/**
* 创建新用户
* @param {object} userData
*/
createUser: async (userData) => {
const response = await apiClient.post(‘/users‘, userData);
return response.data;
}
};
AI 辅助开发与文件结构
在我们最近的一个项目中，我们发现合理的结构能显著提升 AI 编程工具（如 Cursor 或 GitHub Copilot）的效率。
经验分享：当你使用 Cursor 的 INLINECODE38e3e783 功能时，如果你的 INLINECODE4f128c75 和 INLINECODE48a5582b 混在一起，AI 经常会搞混上下文，建议你通过清晰的 INLINECODEb36bf2a1 符号引用。
例如，当你想修改 UserProfile 组件时，你可以直接告诉 AI：
> "@src/features/User/components/UserProfile.jsx 请根据最新的设计稿，使用 @src/shared/components/atoms/Button 重新优化这个页面的样式。"
这种基于语义的文件夹命名，正是 2026 年 “氛围编程” 的核心理念：让 AI 成为你的结对编程伙伴，而不是简单的代码补全工具。
常见错误与性能优化建议
在构建项目结构时，我们还要注意避开一些常见的“坑”：
- 避免嵌套过深：尽量避免创建超过 4-5 层的文件夹嵌套。这会导致文件路径极长，不仅难以阅读，在导入时也会非常痛苦。
- 滥用
components文件夹：不要把所有东西都往里塞。学会区分“通用组件”（UI 库，如 Button）和“业务组件”（特定业务逻辑，如 UserProfileCard）。 - 忽视路径别名：当项目变大时，使用 INLINECODE9c581217 这种相对路径简直是噩梦。我们可以在 INLINECODE471b0720 或 INLINECODE821e4719 中配置路径别名，将其简化为 INLINECODE5040ad20。
配置示例 (vite.config.js)：
import { defineConfig } from ‘vite‘
import react from ‘@vitejs/plugin-react‘
import path from ‘path‘
// https://vitejs.dev/config/
export default defineConfig({
plugins: [react()],
resolve: {
alias: {
‘@‘: path.resolve(__dirname, ‘./src‘),
‘@components‘: path.resolve(__dirname, ‘./src/shared/components‘),
‘@features‘: path.resolve(__dirname, ‘./src/features‘),
},
},
})
结语
React 给了我们极大的自由度，但也正因如此，如何组织代码完全取决于我们自己的决策。一个精心设计的文件夹结构，是成为一名专业 React 开发者的必经之路。
通过我们在本文中讨论的方法——从基础的分类到“基于功能”的模块化结构，再到结合 AI 工作流的 2026 年新范式——你现在已经拥有了构建可扩展、易维护应用的蓝图。
下一步行动建议：
- 回顾你目前的一个项目，试着将其中的一个模块重构为上述的 Feature-based 结构。
- 配置你的
vite.config.js，开始使用路径别名导入。 - 尝试使用 Cursor 或 Copilot，对某个特定的 Service 文件进行重构，体验 AI 在结构化代码上的强大能力。
开始动手吧，你的代码库（以及未来的你）会感谢你的！