企业官网建设流程全解析

1. 从“rea”这个标题说起：一个被低估的缩写背后藏着什么

第一次看到“rea”这个标题的时候，我脑子里蹦出来的第一反应是——这大概率又是一个被缩写玩坏了的项目名。做技术的人都有个毛病，喜欢把长名字砍成三四个字母，仿佛名字越短越显得内行。但“rea”这个组合有点意思，它不像“api”“sdk”“orm”那样有明确的行业共识，也不像“abc”“xyz”那样一看就是随手打的占位符。它更像是一个刻意选择的缩写，背后指向某个具体的概念或工具链。

我后来花了不少时间去琢磨这个标题可能的指向。结合当前技术社区里高频出现的一些讨论方向，“rea”最有可能指向的是React 生态中的某个实践集合（React Ecosystem Architecture 的缩写变体），也可能是实时事件分析（Real-time Event Analytics）的简写，还有一定概率是资源评估与分配（Resource Evaluation & Allocation）在运维领域的落地项目代号。不管是哪一种，这个标题本身就透露出一个信号：作者想聊的不是某个单点技术，而是一套组合拳。

为什么我敢这么判断？因为单字母或三字母缩写在技术圈有个规律——越是短的缩写，往往承载的抽象层级越高。你看“OS”是操作系统，“DB”是数据库，“ML”是机器学习，都是大领域级别的概念。所以“rea”大概率也不是在讲某个具体的函数或者库，而是在讲一套方法论、一个架构思路、或者一种工程实践的组合。

这篇文章我打算按照“React 生态架构实践”这个方向来展开，原因有三：第一，这是当前前端领域讨论热度最高、覆盖面最广的方向之一；第二，它天然包含“选型、搭建、优化、排错”的完整链路，适合做深度拆解；第三，这个方向对读者的普适性最强，不管你是刚入行的前端新人，还是带团队的技术负责人，都能从中找到对自己有用的东西。当然，如果你理解的“rea”是其他方向，文中的很多思路和排查方法同样可以迁移过去，因为工程实践的底层逻辑是相通的。

这篇文章适合谁看？如果你正在搭建一个中大型前端项目，纠结于技术选型和架构分层，那这篇内容会对你有直接帮助。如果你已经有一套跑着的系统，但总觉得哪里不对劲——构建慢、状态乱、组件耦合严重——那这篇内容也能帮你理清排查思路。哪怕你只是刚学完基础语法，想看看真实项目里到底怎么组织代码，我也会尽量把每个决策背后的“为什么”讲清楚，让你能跟上节奏。

接下来我会从整体设计思路、核心细节拆解、实操落地过程、常见问题排查四个维度展开，每个部分都会配上我实际踩过的坑和验证过的方案。不堆概念，不抄文档，只讲能直接拿去用的东西。

2. 整体架构设计与技术选型思路

2.1 为什么架构设计要从“约束条件”出发而不是从“技术栈”出发

我见过太多项目一上来就讨论“用 React 还是 Vue”“上 Next.js 还是 Vite”“状态管理选 Redux 还是 Zustand”，讨论得热火朝天，但没人问一句：我们这个项目到底面临什么约束？团队几个人？迭代频率多高？首屏性能要求是多少？SEO 有没有硬需求？这些约束条件没搞清楚，选什么技术栈都是拍脑袋。

我的习惯是先把约束条件列出来，分成三类：团队约束、业务约束、运维约束。团队约束包括人数、技术背景、人员流动率；业务约束包括功能复杂度、迭代节奏、性能指标；运维约束包括部署环境、监控能力、回滚要求。这三类约束一摆出来，技术选型的范围基本就收窄了百分之七八十。

举个例子，假设你是一个三到五人的前端团队，业务是一个中后台管理系统，迭代频率是两周一个版本，没有 SEO 需求，部署在内网环境。那我的建议就很明确：Vite + React + TypeScript + Zustand + React Router，不要上 Next.js，不要上 Redux Toolkit 的复杂 slice 模式，不要搞微前端。为什么？因为三五个人的团队维护不了那么重的架构，中后台系统对首屏性能的容忍度相对高，内网部署意味着你不需要考虑 CDN 和边缘渲染那一套。把省下来的精力放在业务逻辑的清晰度和组件复用上，收益大得多。

反过来，如果你做的是一个面向 C 端的电商前台，团队有十个人以上，迭代频率是每周甚至每天，SEO 和首屏性能都是硬指标，那 Next.js 或者 Remix 这类带服务端渲染能力的框架就是更合理的选择。状态管理可能需要 Zustand 配合 React Query 做服务端状态和客户端状态的分离。构建产物要做精细的代码分割和预加载策略。这些决策都不是拍脑袋来的，而是从约束条件推导出来的。

2.2 分层架构的核心原则：让每一层只关心一件事

前端项目最容易出现的问题就是“什么都往组件里塞”。一个组件里既有数据请求，又有状态管理，又有业务逻辑，又有 UI 渲染，最后这个组件变成了一坨谁都不敢动的代码。我的做法是强制分层，每一层只关心一件事。

第一层是视图层，只负责渲染 UI 和捕获用户交互。这一层的组件应该是“纯”的，给它什么 props 它就渲染什么，不关心数据从哪来，也不关心点击之后发生了什么。这样做的好处是视图层可以独立测试，可以用 Storybook 单独预览，改样式的时候不用担心把逻辑改坏。

第二层是状态层，负责管理应用的状态。这里要区分两种状态：服务端状态和客户端状态。服务端状态是指从后端拿来的数据，比如用户信息、订单列表、商品详情，这类状态的特点是“有缓存、会过期、需要重新验证”，我一般用 React Query 或者 SWR 来管理。客户端状态是指 UI 的状态，比如弹窗开没开、表单填了什么、当前选中的 tab 是哪个，这类状态用 Zustand 或者 Jotai 管理就够了。把这两种状态混在一起管理，是很多项目状态混乱的根源。

第三层是逻辑层，负责处理业务规则。比如“下单前要校验库存”“优惠券不能和积分同时使用”“超过三次失败要锁定账号”，这些规则不应该写在组件里，也不应该写在状态管理里，而应该抽成独立的函数或者 hooks。这一层是项目里最值得写单元测试的地方，因为业务规则最容易出错，也最值得保护。

第四层是服务层，负责和后端 API 打交道。这一层要做的事情包括：请求的封装、错误的统一处理、请求拦截和响应拦截、类型定义。我习惯用 axios 或者 fetch 封装一个统一的 request 函数，所有 API 调用都走这个函数，这样加日志、加 token、加重试逻辑都只需要改一个地方。

这四层之间的依赖关系是单向的：视图层依赖状态层和逻辑层，状态层依赖服务层，逻辑层依赖服务层。反过来不行。如果你发现视图层直接调了服务层的 API，或者状态层里写了业务规则，那就说明分层被破坏了，需要重构。

2.3 目录结构设计：让新人三天内能找到任何代码

目录结构这件事看起来简单，但我见过太多项目在这上面翻车。有的项目按文件类型分目录，所有组件放一个文件夹，所有 hooks 放一个文件夹，所有工具函数放一个文件夹。项目小的时候还行，项目一大就完蛋——你改一个功能要同时打开五六个文件夹，改完还不知道有没有漏。

我的做法是按功能域分目录，功能域内部再按类型分。顶层目录长这样：

src/ features/ user/ components/ hooks/ services/ stores/ utils/ types.ts index.ts order/ components/ hooks/ services/ stores/ utils/ types.ts index.ts shared/ components/ hooks/ utils/ types/ app/ routes/ layouts/ providers/

这样分的好处是：当你接到一个“修改用户头像上传逻辑”的需求时，你只需要打开features/user/这一个目录，所有相关代码都在里面。shared/放的是跨功能域复用的东西，比如通用的按钮组件、日期格式化函数、全局类型定义。app/放的是应用级别的配置，比如路由表、布局组件、全局 Provider。

每个功能域的index.ts是它的公开接口，只导出其他功能域需要用到的东西。功能域内部的组件、hooks、工具函数默认不对外暴露。这样做的好处是功能域之间的耦合度降到最低，你改 user 模块的内部实现，只要index.ts的导出没变，order 模块就不需要动。

注意：不要过度设计目录结构。我见过有人把每个功能域又拆成 domain、application、infrastructure 三层，结果一个简单的增删改查要跨六个文件夹。目录结构的复杂度应该和项目的复杂度匹配，三五个人的项目搞那么复杂纯粹是给自己找麻烦。

2.4 构建工具选型：Vite 和 Webpack 的真实差距在哪里

构建工具的选择是另一个容易引发争论的话题。我的观点很明确：新项目一律用 Vite，老项目如果 Webpack 跑得动就不要折腾。为什么？因为 Vite 在开发体验上的优势是碾压级的。

Webpack 的开发服务器启动时，需要先把所有模块打包一遍，项目大了之后启动时间动辄一两分钟。Vite 利用浏览器原生的 ES Module 支持，开发服务器启动时几乎不需要打包，你改哪个文件它就编译哪个文件，启动时间通常在几秒以内。这个差距在大型项目里非常明显——你一天可能要重启十次开发服务器，每次省一分钟，一天就省十分钟，一个月就是好几个小时。

但 Vite 也不是没有代价。它的生产构建用的是 Rollup，在某些极端场景下（比如需要非常精细的代码分割控制、需要特殊的 loader 处理）不如 Webpack 灵活。不过对于百分之九十的项目来说，Vite 的生产构建完全够用，而且配置比 Webpack 简单得多。

如果你确实需要从 Webpack 迁移到 Vite，我的建议是渐进式迁移，不要一次性全改。先把开发服务器换成 Vite，生产构建继续用 Webpack，跑一段时间确认没问题之后再切生产构建。迁移过程中最容易出问题的地方是：环境变量的处理方式不同、静态资源的引用方式不同、某些 Webpack 特有的 loader 没有对应的 Vite 插件。这些都需要提前排查。

3. 核心细节解析与实操要点

3.1 状态管理的边界划分：什么该放全局，什么该放局部

状态管理是前端项目里最容易过度设计的地方。我见过太多项目把什么状态都往全局 store 里塞，结果 store 变成了一个巨大的垃圾场，谁都不敢删东西，因为不知道删了会不会影响别的功能。

我的原则很简单：只有跨组件、跨路由、跨层级共享的状态才放全局，其他一律放局部。具体来说，以下几类状态适合放全局：

• 用户认证信息：当前登录用户是谁、有什么权限、token 是什么。这些信息几乎每个页面都要用，放全局合理。
• 应用级别的配置：主题、语言、时区、功能开关。这些是全局生效的，放全局合理。
• 跨路由的临时数据：比如从列表页跳到详情页时需要传递的筛选条件。这种数据用 URL 参数或者全局 store 都行，我倾向于用 URL 参数，因为可以分享和刷新。

以下几类状态不应该放全局：

• 表单的输入值：表单状态应该由表单组件自己管理，用 React Hook Form 或者 Formik 这类库，不要往全局 store 里塞。
• 弹窗的开关状态：哪个弹窗开没开，应该由触发它的组件管理，或者用 URL 参数控制。
• 列表的滚动位置：这种状态用浏览器的 history 或者 sessionStorage 管理更合适。
• 服务端数据的缓存：这类状态交给 React Query 或者 SWR，不要自己用全局 store 手动管理缓存和失效逻辑。

我见过一个项目把表单的每个字段都放到了 Redux 里，结果改一个输入框要 dispatch 一个 action，性能差不说，代码还特别难维护。后来重构的时候把表单状态收回到组件内部，代码量减少了百分之四十，性能也上去了。

3.2 组件设计的粒度控制：什么时候该拆，什么时候不该拆

组件拆分是另一个容易走极端的点。有的人一个组件写一千行，有的人一个按钮都要拆成三个组件。我的判断标准是：当一个组件同时满足“逻辑复杂”和“可复用”两个条件时，才值得拆。

具体来说，以下几种情况应该拆组件：

• 同一个 UI 在多个地方出现：比如商品卡片、用户头像、价格显示。这种拆出来做成通用组件，改一处就能全局生效。
• 组件内部有明显的逻辑分区：比如一个页面组件里，头部、筛选区、列表区、分页区各自独立，那就可以拆成四个子组件。拆完之后每个子组件的代码量控制在两百行以内，可读性会好很多。
• 组件需要独立测试：如果一个组件的逻辑比较复杂，拆出来单独写测试会方便很多。

以下几种情况不应该拆组件：

• 只是为了减少行数：把一个两百行的组件拆成四个五十行的组件，如果这四个组件之间 props 传了一大堆，那还不如不拆。拆分的目的是降低复杂度，不是减少行数。
• 组件只在当前文件用一次：如果这个组件不会被其他地方复用，也不会被单独测试，那放在同一个文件里反而更清晰。
• 拆分后 props 超过七个：如果一个组件需要传七个以上的 props，说明它的职责太多了，应该先考虑合并 props 或者重新设计接口，而不是继续拆。

我个人的经验值是：一个 React 组件的代码量控制在三百行以内，props 数量控制在五个以内。超过这个值就要考虑拆分了。当然这不是硬性规定，只是一个参考线。

3.3 API 层的封装策略：统一入口、统一错误处理、统一类型

API 层是前端和后端的边界，这一层封装得好不好，直接决定了后续开发的效率。我的做法是所有 API 调用都走一个统一的 request 函数，这个函数负责以下几件事：

• 基础配置：baseURL、超时时间、默认 headers。
• 请求拦截：自动带上 token、自动序列化参数、自动处理 loading 状态。
• 响应拦截：统一处理 HTTP 错误码、统一处理业务错误码、自动刷新 token。
• 错误处理：网络错误、超时错误、业务错误分别怎么提示用户。
• 类型定义：请求参数和响应数据的 TypeScript 类型。

这样做的好处是，当后端改了错误码规范，或者需要加一个新的请求头，你只需要改这一个函数，所有 API 调用自动生效。如果每个 API 都自己写 axios 调用，那改起来就是灾难。

具体实现上，我习惯用 axios 的拦截器来做。请求拦截器里从 store 或者 localStorage 里拿 token 塞到 header 里，响应拦截器里判断 HTTP 状态码和业务状态码，如果是 401 就跳转登录页，如果是其他错误就弹 toast 提示。这里有个细节：不要在每个 API 调用里都写 try-catch，错误处理应该在拦截器里统一做，业务代码里只需要处理成功的情况。

类型定义这块，我强烈建议用 TypeScript，而且不要用any。后端的接口文档如果是 Swagger 或者 OpenAPI 格式，可以用工具自动生成类型定义，省得手写。如果是手写，那至少要把请求参数和响应数据的类型定义清楚，这样在组件里用的时候有自动补全，改接口的时候也能快速找到所有受影响的地方。

3.4 性能优化的优先级排序：先测量，再优化

性能优化最容易犯的错误是“凭感觉优化”。我见过有人花了一周时间做代码分割和懒加载，结果 Lighthouse 分数只涨了两分，因为真正的瓶颈是首屏的一个大图片没有压缩。

我的做法是先测量，再优化，优化完再测量。测量的工具包括：

• Lighthouse：看首屏性能、可访问性、SEO 的总体评分。
• Chrome DevTools 的 Performance 面板：看具体的渲染耗时、脚本执行耗时、布局偏移。
• React DevTools 的 Profiler：看组件的渲染次数和渲染耗时。
• Bundle Analyzer：看打包产物的体积分布，找出体积最大的依赖。

测量的目的是找到真正的瓶颈。常见的瓶颈有这么几类：

• 首屏加载慢：可能是 bundle 太大、关键资源没有预加载、服务端响应慢。
• 交互卡顿：可能是组件渲染次数太多、长列表没有虚拟化、频繁的 re-render。
• 内存泄漏：可能是事件监听没有清理、定时器没有清除、闭包引用了大对象。

针对不同的瓶颈，优化手段也不一样。首屏加载慢就做代码分割、资源压缩、预加载；交互卡顿就做 memo 优化、虚拟列表、防抖节流；内存泄漏就检查 useEffect 的清理函数、检查事件监听和定时器。

注意：不要过早优化。项目初期最重要的是把功能做对，性能只要不差到影响使用就行。等到功能稳定了，再根据实际的性能数据做针对性优化。过早优化不仅浪费时间，还会让代码变得难以维护。

4. 实操过程与核心环节实现

4.1 项目初始化：从零搭建一个可用的开发环境

假设我们现在要从零搭建一个 React 项目，技术栈选型是 Vite + React + TypeScript + Zustand + React Query + React Router。下面是我实际操作的步骤。

第一步，用 Vite 的脚手架创建项目：

npm create vite@latest my-project -- --template react-ts cd my-project npm install

第二步，安装核心依赖：

npm install react-router-dom zustand @tanstack/react-query axios npm install -D @types/node

第三步，配置路径别名。在vite.config.ts里加上：

import { defineConfig } from 'vite' import react from '@vitejs/plugin-react' import path from 'path' export default defineConfig({ plugins: [react()], resolve: { alias: { '@': path.resolve(__dirname, './src'), }, }, })

同时在tsconfig.json的compilerOptions里加上：

{ "baseUrl": ".", "paths": { "@/*": ["src/*"] } }

这样做的好处是 import 的时候可以用@/features/user代替../../features/user，路径清晰很多，重构的时候也不用改一堆相对路径。

第四步，配置 React Query 的 Provider。在src/app/providers/下新建QueryProvider.tsx：

import { QueryClient, QueryClientProvider } from '@tanstack/react-query' import { ReactNode } from 'react' const queryClient = new QueryClient({ defaultOptions: { queries: { staleTime: 5 * 60 * 1000, retry: 1, refetchOnWindowFocus: false, }, }, }) export function QueryProvider({ children }: { children: ReactNode }) { return ( <QueryClientProvider client={queryClient}> {children} </QueryClientProvider> ) }

这里的staleTime设为五分钟，意思是数据在五分钟内被认为是新鲜的，不会重新请求。retry设为 1，意思是请求失败后重试一次。refetchOnWindowFocus设为 false，意思是窗口重新获得焦点时不自动刷新。这三个配置是我在实际项目中总结出来的比较合理的默认值，你可以根据自己的业务特点调整。

第五步，配置路由。在src/app/routes/下新建index.tsx：

import { createBrowserRouter } from 'react-router-dom' import { MainLayout } from '@/app/layouts/MainLayout' import { UserListPage } from '@/features/user/pages/UserListPage' import { OrderListPage } from '@/features/order/pages/OrderListPage' export const router = createBrowserRouter([ { path: '/', element: <MainLayout />, children: [ { path: 'users', element: <UserListPage /> }, { path: 'orders', element: <OrderListPage /> }, ], }, ])

第六步，在src/main.tsx里组装：

import React from 'react' import ReactDOM from 'react-dom/client' import { RouterProvider } from 'react-router-dom' import { QueryProvider } from '@/app/providers/QueryProvider' import { router } from '@/app/routes' import './index.css' ReactDOM.createRoot(document.getElementById('root')!).render( <React.StrictMode> <QueryProvider> <RouterProvider router={router} /> </QueryProvider> </React.StrictMode> )

到这里，一个基本的开发环境就搭好了。启动开发服务器：

npm run dev

正常情况下几秒钟之内就能看到页面。如果启动失败，大概率是依赖版本冲突或者路径别名配置有问题，检查一下vite.config.ts和tsconfig.json的配置是否一致。

4.2 一个完整功能模块的实现：从 API 到 UI 的完整链路

我们以“用户列表”这个功能为例，走一遍从 API 到 UI 的完整链路。

首先在src/features/user/types.ts里定义类型：

export interface User { id: string name: string email: string role: 'admin' | 'editor' | 'viewer' createdAt: string } export interface UserListParams { page: number pageSize: number keyword?: string } export interface UserListResponse { list: User[] total: number }

然后在src/features/user/services/userApi.ts里定义 API 调用：

import { request } from '@/shared/utils/request' import { UserListParams, UserListResponse, User } from '../types' export const userApi = { getList(params: UserListParams) { return request.get<UserListResponse>('/api/users', { params }) }, getDetail(id: string) { return request.get<User>(`/api/users/${id}`) }, update(id: string, data: Partial<User>) { return request.put<User>(`/api/users/${id}`, data) }, delete(id: string) { return request.delete(`/api/users/${id}`) }, }

接着在src/features/user/hooks/useUserList.ts里封装 React Query 的 hook：

import { useQuery } from '@tanstack/react-query' import { userApi } from '../services/userApi' import { UserListParams } from '../types' export function useUserList(params: UserListParams) { return useQuery({ queryKey: ['users', params], queryFn: () => userApi.getList(params), keepPreviousData: true, }) }

这里的queryKey包含了 params，意思是当 params 变化时自动重新请求。keepPreviousData设为 true，意思是翻页的时候保留上一页的数据，避免页面闪烁。

然后在src/features/user/components/UserTable.tsx里写表格组件：

import { User } from '../types' interface UserTableProps { data: User[] loading: boolean onEdit: (user: User) => void onDelete: (user: User) => void } export function UserTable({ data, loading, onEdit, onDelete }: UserTableProps) { if (loading) return <div>加载中...</div> if (!data.length) return <div>暂无数据</div> return ( <table> <thead> <tr> <th>姓名</th> <th>邮箱</th> <th>角色</th> <th>操作</th> </tr> </thead> <tbody> {data.map((user) => ( <tr key={user.id}> <td>{user.name}</td> <td>{user.email}</td> <td>{user.role}</td> <td> <button onClick={() => onEdit(user)}>编辑</button> <button onClick={() => onDelete(user)}>删除</button> </td> </tr> ))} </tbody> </table> ) }

最后在src/features/user/pages/UserListPage.tsx里组装页面：

import { useState } from 'react' import { useUserList } from '../hooks/useUserList' import { UserTable } from '../components/UserTable' export function UserListPage() { const [page, setPage] = useState(1) const [keyword, setKeyword] = useState('') const { data, isLoading } = useUserList({ page, pageSize: 20, keyword }) const handleEdit = (user) => { // 打开编辑弹窗 } const handleDelete = (user) => { // 确认后调用删除接口 } return ( <div> <input value={keyword} onChange={(e) => setKeyword(e.target.value)} placeholder="搜索用户" /> <UserTable data={data?.list ?? []} loading={isLoading} onEdit={handleEdit} onDelete={handleDelete} /> <Pagination current={page} total={data?.total ?? 0} pageSize={20} onChange={setPage} /> </div> ) }

这条链路走下来，你会发现每一层的职责都很清晰：types 定义数据结构，services 负责请求，hooks 负责状态管理，components 负责渲染，pages 负责组装。改需求的时候，你知道该改哪一层，不会牵一发而动全身。

4.3 构建与部署：从开发环境到生产环境的最后一公里

开发环境跑通了，接下来要解决构建和部署的问题。Vite 的构建命令很简单：

npm run build

构建产物默认在dist/目录下。但直接把这个目录扔到服务器上是不够的，还需要做一些配置。

首先是环境变量的处理。Vite 支持.env文件，但只有以VITE_开头的变量才会暴露给客户端代码。我一般会建三个文件：.env（所有环境共用）、.env.development（开发环境）、.env.production（生产环境）。比如：

# .env VITE_APP_TITLE=我的应用 # .env.development VITE_API_BASE_URL=http://localhost:3000 # .env.production VITE_API_BASE_URL=https://api.example.com

在代码里用import.meta.env.VITE_API_BASE_URL来读取。注意不要在前端代码里放敏感信息，因为所有VITE_开头的变量都会被打包到客户端代码里，任何人都能看到。

然后是路由的 history 模式配置。如果你用的是createBrowserRouter，部署的时候需要配置服务器把所有未匹配的路径都指向index.html，否则刷新页面会 404。Nginx 的配置大概是这样的：

location / { try_files $uri $uri/ /index.html; }

最后是缓存策略。Vite 构建出来的静态资源文件名都带 hash，比如index-a1b2c3d4.js，所以可以设置长期缓存：

location /assets/ { expires 1y; add_header Cache-Control "public, immutable"; }

但index.html不能缓存，否则用户永远拿不到新版本：

location = /index.html { add_header Cache-Control "no-cache, no-store, must-revalidate"; }

这套配置跑下来，用户第一次访问加载所有资源，之后访问只加载index.html和变化的资源，速度会快很多。

5. 常见问题与排查技巧实录

5.1 开发环境常见问题速查

5.2 生产环境常见问题速查

5.3 几个我踩过的坑和对应的解法

第一个坑：React Query 的queryKey设计不合理导致缓存失效。我一开始把queryKey写成['users']，结果翻页的时候数据不更新，因为 React Query 认为 key 没变就不重新请求。后来改成['users', params]，params 变化时自动重新请求。这个坑的教训是：queryKey里要包含所有影响请求结果的参数，否则缓存会出问题。

第二个坑：Zustand 的 selector 写法导致不必要的重渲染。我一开始写const { user, setUser } = useUserStore()，结果 store 里任何状态变化都会导致组件重渲染。后来改成const user = useUserStore((state) => state.user)，只有 user 变化时才重渲染。这个坑的教训是：用 Zustand 一定要用 selector，不要直接解构整个 store。

第三个坑：Vite 的import.meta.env在测试环境读不到值。我用 Vitest 写单元测试的时候，发现import.meta.env.VITE_API_BASE_URL是 undefined。后来查文档才知道，Vitest 需要单独配置环境变量，在vitest.config.ts里用define或者env来注入。这个坑的教训是：测试环境的环境变量配置和开发环境是分开的，需要单独处理。

第四个坑：TypeScript 的路径别名在构建时失效。开发的时候用@/没问题，但构建出来的产物运行时报错找不到模块。原因是 Vite 的 alias 只影响开发服务器和构建时的模块解析，如果用了tsc做类型检查，还需要在tsconfig.json里配置paths。这个坑的教训是：路径别名要在 Vite 和 TypeScript 两处都配置，缺一不可。

5.4 性能排查的实操流程

当你觉得页面卡顿的时候，不要凭感觉猜，按照下面的流程走一遍：

第一步，打开 Chrome DevTools 的 Performance 面板，点击录制，操作页面，停止录制。看火焰图里哪个函数占用的时间最长。如果是某个组件的 render 函数占用时间长，那说明这个组件需要做 memo 优化或者拆分。

第二步，打开 React DevTools 的 Profiler 面板，点击录制，操作页面，停止录制。看哪个组件渲染次数最多，哪个组件渲染耗时最长。如果某个组件在父组件状态变化时频繁重渲染，但它的 props 其实没变，那就用React.memo包一下。

第三步，打开 Network 面板，看有没有重复的请求、有没有大文件没有压缩、有没有请求瀑布。如果有重复请求，检查 React Query 的queryKey和staleTime配置。如果有大文件，检查构建配置里的压缩和代码分割。

第四步，打开 Lighthouse，跑一次完整评估。看首屏性能、可访问性、最佳实践、SEO 四个维度的评分。Lighthouse 会给出具体的优化建议，比如“消除阻塞渲染的资源”“减少未使用的 JavaScript”“为静态资源设置缓存策略”。按照建议逐条优化就行。

这套流程走下来，百分之九十的性能问题都能定位到具体原因。剩下的百分之十可能是浏览器兼容性问题或者第三方库的 bug，那就需要更深入的排查了。

5.5 团队协作中的规范建议

最后聊几个团队协作中容易出问题的地方。第一个是代码风格不统一，解决方案是上 ESLint 和 Prettier，在提交代码前自动格式化和检查。第二个是提交信息混乱，解决方案是用 Commitlint 加 Husky，强制提交信息符合规范。第三个是分支管理混乱，解决方案是定一个简单的 Git Flow，比如main分支只放稳定版本，develop分支放开发中的版本，功能分支从develop切出来，完成后合并回去。

这些规范看起来是小事，但团队大了之后，没有规范会浪费大量时间在沟通和返工上。我的建议是项目一开始就把这些规范定好，后面省心很多。

我个人在实际操作中的体会是，前端项目的复杂度不在于技术本身，而在于如何组织代码和团队协作。技术选型没有绝对的对错，关键是选一个团队能驾驭的方案，然后坚持执行下去。架构设计也不是一蹴而就的，而是在迭代中不断调整和优化的。每次遇到问题的时候，多问几个“为什么”，找到根本原因，比急着打补丁要有效得多。