经历过几次欲哭无泪的重构后，我深刻体会到一个血淋淋的教训： 你组织 React 应用结构的方式，直接决定了你每天是在优雅地创造，还是在屎山里痛苦地考古。

项目刚启动时，一切看起来都很单纯。几个组件、两三个文件夹，任谁都能闭着眼睛轻松导航。然而，只要给项目几周时间——新需求排山倒海般涌入，代码文件疯狂裂变，原本清爽的目录结构瞬间就会像杂草一样野蛮生长。

这种痛苦我体验过不止一次。

有时候，你为了改个样式，得在密密麻麻的目录树里翻找五分钟才想起那个组件藏在哪；还有时候，一个微小的业务改动，居然需要你同时修改三四个不同地方的文件。一旦出现这种苗头，就说明你的架构已经开始向“屎山”退化了。

在我看来，构建一个应用程序和在现实世界里盖大楼没什么两样。

地基打得稳，往上加盖任何花里胡哨的楼层都会让人心里踏实；地基要是歪的，随着楼层越来越高，各种墙体开裂、漏水的问题就会接踵而至。React 项目同样如此。一套优秀的目录架构不会让你的业务逻辑自动变得完美，但它能让你在面对业务体量暴增时，依然能做到兵来将挡，游刃有余。

今天，我想毫无保留地分享 10 个我一直在身体力行的 React 整顿思路。它们都不难理解，但如果你能从今天开始坚持落实，相信我，你的代码库绝对会变得前所未有的干净利落。

按业务功能聚类，而不是按技术层级分堆

当项目还处于幼年期时，你怎么分文件夹都无所谓。但当项目一旦有了规模，文件怎么摆放就会直接决定你的工作效率。如果团队成员每天都在互相灵魂拷问“这个组件放哪了？”或者“哪一个文件才是控制这个页面的？”，那说明现有的架构已经是你的绊脚石了。

最常见的误区就是“技术一刀切”——纯粹按照代码的技术属性把它们归类到不同的文件夹里。

不要为了技术分层而分层

很多项目一上来就喜欢摆出这样的阵势：

/src
│
├── components
│   ├── Header.js
│   ├── Footer.js
│   ├── Hero.js
├── containers
│   ├── InvoicesContainer.js
│   ├── PaymentProfilesContainer.js
│
├── presenters
│   ├── InvoicesPresenter.js
│   ├── PaymentProfilesPresenter.js

乍看之下井井有条对吧？但只要业务稍微一铺开，这种结构就会把本来强相关的代码无情地拆散到天涯海角。如果你今天被指派去修一个发票（Invoices）模块的 Bug，你不得不被迫在 components、containers、presenters 之间反复横跳、疯狂切屏。这种无意义的上下文切换会极其严重地消耗你的开发专注力。

以产品功能或页面模块为中心进行归类

更务实、更符合人类直觉的做法是：以用户在产品里看到的功能或页面为边界，让强相关的代码“抱团取暖”。

我们可以像这样改造：

/src
│
├── features
│   ├── billing
│   │   ├── invoices
│   │   │   ├── index.js
│   │   │   └── ...
│   │
│   │   ├── payment-profiles
│   │   │   ├── index.js
│   │   │   └── ...
│   │
│   ├── login
│   │   ├── index.js
│   │   └── ...

现在，所有和发票（invoices）相关的逻辑全都收拢在同一个屋檐下了。你要改发票模块？直接点开 billing/invoices，组件、容器、对应的类型定义全在这里。不需要全工程地毯式搜索，也不用去猜别人把文件藏在了哪个技术分层里。随着项目体积的膨胀，这种基于领域的结构能非常自然地向下延伸，绝对不会乱套。

别让复杂组件委曲求全，给它们独立的单间

在 React 里，组件通常是一步步变胖的。一个组件刚写出来的时候可能只有几十行，但随着时间推移，它不可避免地会衍生出专属的子组件、样式表、测试脚本或者类型定义（Types）。如果你把这些衍生文件全都一股脑地平铺在全局的大目录下，整个组件库很快就会乱得像个垃圾场。

因此，只要一个 UI 组件稍微显露出复杂的苗头，就应该立刻执行“分家”，让它拥有自己独立的专属文件夹。

拒绝把所有组件硬塞进单文件列表

刚开始的时候，你可能会觉得这样很省事：

/src
│
├── components
│   ├── Notification.tsx
│   ├── ModalWindow.tsx
│   ├── UserBadge.tsx
│   ├── LoadingSpinner.tsx
│   └── ...

但当 Notification 开始需要自己的小 Icon、独立的测试逻辑、甚至是 Storybook 文档时，单文件就会开始失控，大目录也会被各种后缀的文件塞满，让人窒息。

实行“一组件一目录”制

让每个有深度的组件都各自自成一派：

/src
│
├── components
│
│   ├── modal-window
│   │   ├── index.ts
│   │   └── ...
│
│   ├── notification-banner
│   │   ├── index.ts
│   │   ├── types.ts
│   │   ├── NotificationBanner.tsx
│   │   ├── NotificationIcon.tsx
│   │   ├── NotificationBanner.test.tsx
│   │   ├── NotificationBanner.stories.tsx
│   │   └── ...

看，世界瞬间清净了。当你想对通知栏（notification-banner）动刀时，点开这个文件夹，核心逻辑、子组件、类型定义、单元测试和组件文档整整齐齐地一字排开。这种高聚合的改动体验，能帮大型组件库省下无数的维护心智。

用绝对路径导入，砸碎“回家的诱惑”

随着项目深度的增加，文件嵌套层级会越来越深。这时候最让人血压飙升的，莫过于在文件头部看到一长串像摩斯密码一样的相对路径引入。

拒绝套娃式的相对路径

如果你的文件藏得深，你可能会写出类似下面这种让人头晕目眩的代码：

import { calculateTotal } from '../../../../helpers/cart';

这种代码不仅丑陋、难以阅读，最致命的是它极度脆弱。只要你哪天看这个组件不顺眼，想把它往上或往下挪一个目录层级，这一整排的 ../ 就会瞬间集体罢工，报出一堆找不到模块的红字错误。

配置绝对路径别名

赶紧通过构建工具（如 Vite、Webpack 或 tsconfig）配个路径别名，把根目录或常用目录锚定住。

配置完之后，你的代码会变成这样：

import { calculateTotal } from '@helpers/cart';

清爽、干净，且坚不可摧。不管你怎么重构目录、怎么移动这个组件的位置，这个绝对路径引入都稳如泰山，再也不用手动去数到底有几层 ../ 了。

提炼公共仓，别让复用逻辑到处流浪

在开发过程中，你会频繁发现某些代码在不同的模块里反复出现。比如一些基础的 UI 控件、通用的自定义 Hook（如控制显隐的、本地存储的），或者是金额格式化的工具函数。如果大家都图省事，随手把这些代码复制粘贴到各自的业务目录下，那代码库的维护噩梦就正式开始了。

最明智的做法是建立一个核心的“公共共享模块”（Shared Module），让所有可复用的轮子都统一归档。

把共享逻辑像沙子一样撒在各个 feature 里

一旦公共代码缺乏归宿，大家就会各自占山为王，导致同一个功能的工具函数在项目的 A 文件夹和 B 文件夹里分别被实现了一遍，甚至两边的实现细节还不太一样。

划定一块神圣的公共共享区

在工程的骨架里，专门预留出一个专属的公共目录：

/src
│
├── shared
│
│   ├── ui
│   │   ├── modal
│   │   │   └── index.js
│   │   │
│   │   ├── input-field
│   │   │   └── index.js
│   │
│   ├── hooks
│   │   ├── useToggle.js
│   │   ├── useLocalStorage.js
│   │
│   ├── helpers
│   │   └── currencyFormatter.js
│
├── features
│   ├── orders
│   │   └── order-history
│   │       └── index.js

这样一来，职责划分就变得黑白分明：只要是可以通用的基础 UI 和纯工具函数，一律进 shared；而具体的业务线逻辑，则老老实实呆在 features 里。这种清晰的界限不仅能有效遏制代码复制粘贴的现象，还能在无形中逼着团队成员多去复用现有的解决方案。 蚂蚁影视

建立第三方防盗门，别让外部库绑架了你的业务

几乎所有的 React 项目都会大量引入外部的第三方轮子，比如日期处理库、图表组件、表单.管理工具或者特定的 UI 组件库。这些现成的轮子确实能帮我们省下大量时间，但如果你毫无节制地把它们直接满大街地 import 到每一个业务组件里，实际上是在给未来埋雷。

因为开源项目的 API 是会变的，甚至有些库会停止维护。如果哪天团队决定把 A 库换成性能更好的 B 库，而 A 库已经渗透到了上百个文件里，那这次升级基本上等同于全线重构。

直接在业务最深处生吞第三方组件

不要像这样在各个角落直接肉搏第三方库：

// ProductCard.tsximport { Card } from 'some-ui-library';// CheckoutSummary.tsximport { Card } from 'some-ui-library';

一旦这个 some-ui-library 组件库宣布大版本底层重构，或者有严重的内存泄漏必须被替换，你将不得不硬着头皮去修改几十上百个文件。

用自己的 UI 壳子把第三方库包裹起来

在项目内部建一个中转站，让业务只跟你的“内部接口”打交道。

// 业务组件里统一这样引入import { Card } from '@components/ui';

而在你的 @components/ui 内部，再去桥接具体的第三方组件库。这样，第三方库就被你成功“软禁”在了这一层包装里。以后不管你是想给这个卡片换个底层框架，还是想在上面加点全局的魔改样式，你都只需要改动这一处包装文件即可，外面的大片业务代码根本不需要有任何感知。

谨慎处理功能模块之间的利益瓜葛

随着功能越写越多，原本平行的两个独立业务（比如“个人中心”和“收银台”）之间，难免会开始产生交集。最容易让人犯迷糊的，就是当两个 feature 都需要同一个特定的小工具时，图省事直接跨目录去“偷”对方的代码。

这种跨领域的强行依赖，会像隐形的锁链一样，把本该解耦的模块死死捆绑在一起。

跨业务线野蛮拷贝或直接跨界越狱引用

比如这两段代码，看似只是个格式化手机号的小函数，却在两个独立的业务模块里分别占山为王：

// profile/settings/formatPhone.jsexport function formatPhone(number) { /* ... */ }// checkout/address/formatPhone.jsexport function formatPhone(number) { /* ... */ }

这不仅导致了逻辑冗余，未来一旦产品经理要求修改手机号的脱敏格式，你漏改任何一个地方都会酿成线上事故。

及时将其升格为公共依赖

一旦发现某个逻辑跨越了业务边界，不要犹豫，立刻把它从原有的 feature 文件夹中剥离出来，“升格”并挪到全局的共享目录中。

/src
│
├── shared
│   ├── utilities
│   │   └── formatPhone.js
│
├── features
│   ├── profile
│   │   └── settings
│   │       └── index.js
│
│   ├── checkout
│       └── address
│           └── index.js

这样两个模块都可以名正言顺地统一调用：

import { formatPhone } from '@shared/utilities';

让整个工程的依赖树变得清晰可见，每一个 feature 的边界都清清爽爽。

把相关的代码按物理距离焊死

编程界有一个非常质朴却异常好使的铁律，叫做 行为局部性（Locality of Behavior, 简称 LoB）。翻译成大白话就是： 东西要放在离它使用地方最近的位置。

当一个开发人员在接手一个新需求时，他能以多快的速度定位到关联代码，直接决定了他当天的下班时间。如果相关的逻辑散落在天南海北，开发就不得不像个不知疲倦的网民一样，在十几个文件夹之间疯狂地双击、返回。

所以在构建一个功能时，尽量把这个功能专属的副作用 Custom Hook、数据转化 Helper 塞到它自己的特区里，不要急着往全局的公共大池子里扔。

我们可以观察这样一套极具呼吸感的就近架构：

/src
│
├── shared
│   ├── ui
│   ├── hooks
│   └── helpers
│
├── features
│   ├── dashboard
│   │   ├── overview
│   │   │   └── index.js
│   │   │
│   │   ├── activity-feed
│   │   │   └── index.js
│   │
│   │   ├── hooks
│   │   │   ├── useActivityFeed.js
│   │   │   └── useDashboardStats.js
│   │
│   │   ├── helpers
│   │       ├── calculateGrowth.js
│   │       └── formatMetrics.js

看，当你在维护大盘（dashboard）页面时，它专属的数据统计钩子（useDashboardStats）和增长率计算函数（calculateGrowth）就在触手可及的地方。你不需要去全局的根目录里大海捞针，这种高度的自包含性能够大幅度降低新人的认知负荷。

让工具函数保持纯粹，别掺杂功利的业务潜规则

工具函数（Utils/Helpers）存在的初衷，是为了提供一些高频、纯粹、跟具体业务没有任何瓜葛的原子化能力。比如日期格式化、数学计算或者数组去重。

最容易让人踩坑的，就是不知不觉把公司的“业务潜规则”写进了这些本来应该追求纯洁的工具函数里。一旦工具函数和特定的业务逻辑高度耦合，它就彻底失去了灵活性，并且会变得极难进行单元测试。因为业务规则的变化频率，可比纯算法逻辑要快得多。

在底层工具函数里掺沙子

像下面这个看似是个算折扣的工具函数，实际上它已经偷偷把公司的“会员等级定价”这种纯业务规则给硬编码进去了：

export function getDiscountPrice(price, userType) {  if (userType === "premium") {    return price * 0.8;
  }  return price;
}

这会导致这个函数无法在非会员计价的场景中复用，甚至哪天产品说高级会员改成 75 折了，你还得来翻动底层工具。

Utils 只做数学计算，业务逻辑在上一层裁决

工具函数应该只保留最抽象的数学运算，把决定权交还给业务层。

// utils/priceHelpers.js// 它只负责按百分比扣减，完全不知道什么是 premium 会员export function applyPercentage(value, percent) {  return value - value * percent;
}

具体的业务线再去调用这个干净的工具：

// features/pricing/calculateFinalPrice.jsimport { applyPercentage } from "@shared/helpers/priceHelpers";export function calculateFinalPrice(price, userType) {  if (userType === "premium") {    return applyPercentage(price, 0.2); // 业务层决定打八折
  }  return price;
}

这样职责划分就像切豆腐一样干净：工具函数永远保持无状态、可预期；业务规则永远留在离业务最近的 feature 文件夹里。

把业务骨架从 UI 皮肤里抽离出去

React 的组件确实很自由，自由到你可以在里面写任何东西。但这往往也是灾难的开始。很多人喜欢在一个渲染页面的 UI 组件里，顺手把繁重的数组转化、复杂的业务公式、甚至各种状态条件全都铺开写在一起。

这会导致组件文件瞬间逼近上千行，读起来像是在读天书。UI 组件的宿命应该非常纯粹： 它只负责接收数据，然后把数据漂亮地渲染在屏幕上。 至于数据是怎么算出来的，它不应该关心。在 React 里， 自定义 Hook（Custom Hooks） 就是帮 UI 剥离业务灵魂的绝佳手术刀。

让 UI 兼职做账房先生

比如下面这个组件，它既要管 DIV 的渲染，又要亲自去算电子产品的特殊折扣：

function OrderSummary({ items }) {  const total = items.reduce((sum, item) => {    if (item.category === "electronics") {      return sum + item.price * 0.9; // 电子产品打九折
    }    return sum + item.price;
  }, 0);  return <div>Total: {total}</div>;
}

这种混杂着业务计算和标签渲染的代码，不仅难以维护，而且这段打折逻辑也无法在别的地方复用。

把算账的差事外包给自定义 Hook

我们把核心的计算骨架抽成一个独立的 Hook：

// hooks/useOrderTotal.jsexport function useOrderTotal(items) {  return items.reduce((sum, item) => {    if (item.category === "electronics") {      return sum + item.price * 0.9;
    }    return sum + item.price;
  }, 0);
}

这时候，我们的 UI 皮肤组件就会变得清爽无比：

import { useOrderTotal } from "@hooks/useOrderTotal";function OrderSummary({ items }) {  const total = useOrderTotal(items);  return <div>Total: {total}</div>;
}

UI 组件现在重新变得专注、好读，而业务逻辑挪到 Hook 里之后，不仅能极其方便地去写断言测试，还能随心所欲地在其他组件里重复调用。

焊死依赖版本，别给半夜线上报警留机会

每一个前端项目都有一张叫做 package.json 的契约，上面记录了我们向外部借用了哪些力量。但在对待依赖版本的态度上，很多团队都显得过于佛系。 光影天堂

大家往往习惯在版本号前面保留 ^（兼容次级版本升级）或者 ~（兼容补丁升级）的符号。虽然这能让你在本地执行安装时自动享受到库作者的最新底层修复，但在工业级协作中，这种宽泛的版本范围往往是导致“在我电脑上明明是好的”以及“线上打包突然暴毙”的罪魁祸首。

使用松散的版本区间

像下面这样允许自动浮动版本，就是在给未知的改动敞开大门：

{  "dependencies": {    "axios": "^1.3.0",    "zustand": "~4.2.0"
  }
}

一旦某天这些第三方库在发布 1.3.2 补丁时不小心夹带了破坏性变更（Breaking Change），而你的 CI/CD 恰好在这时候触发了线上生产打包，它就会悄悄拉取最新的脏版本，导致线上直接雪崩，而你在本地可能百思不得其解。

把版本号死死钉在确定的数字上

为了让所有人的环境和线上的容器达到像素级的统一，不要在版本号前加任何前缀：

{  "dependencies": {    "axios": "1.3.0",    "zustand": "4.2.0"
  }
}

把版本号死死钉住。配合 package-lock.json 或 yarn.lock，确保团队里的每一个人、测试环境、以及远端的生产服务器，运行的都是字节级一致的代码。

写在最后

你能一口气看到这里，真的说明你是一个对代码有洁癖、对质量有追求的同道中人。

在 React 极其自由的生态里，写出能跑通的代码很容易；但要写出让人赏心悦目、过了半年回头看依然逻辑清晰的代码，确实需要我们付出额外的克制与思考。今天聊到的这 10 个手法，并不会给你的产品带来什么酷炫的动画，但它们能在日常的搬砖生活中，帮你悄悄抹去那些恶心人的摩擦力，让你能把宝贵的心智，全部留给真正有挑战的业务本身。