React 应用开发：从组件到 SSR 与测试

0. 元信息

• 主题路径：docs/topics/react-app/README.md
• 主分类：前端与客户端
• 辅助分类：工程技术
• 适合对象：会用 HTML/CSS/JS、了解 HTTP 与 REST、写过简单交互页面的开发者
• 建议周期：610 周（每周 812 小时，至少 60% 时间写代码）
• 前置知识：JavaScript ES2017+ 模块与异步、http-1-2-3、rest-api-design、命令行与 Node.js
• 最终目标：能独立搭建带路由、状态管理、服务端渲染、测试与监控的可生产 React 应用

1. 学习路线

组件与 JSX
  → Hooks 与状态管理
  → 路由与数据获取
  → 样式与构建工具链
  → 测试、可观测与可访问性
  → SSR / SSG / RSC 与生产部署
  → 综合项目：完整电商 SPA + 配套 RSC 重构

每一步都建立在前一步的稳定结构上；不要跳级把 RSC 提前到没掌握 Suspense 与数据流之前。

2. 阶段周数分配（6~10 周，量力而行）

6 周方案对应高强度、每天投入；10 周方案对应稳扎稳打、留出“踩坑-复盘-改写”时间。选 6 周时建议每周留 1 天只做代码复盘。

3. 七阶段表

陷阱集中在三个：把 useEffect 当万能胶水、过早引入 Redux、把 SSR 当 SPA 升级版。每个阶段都对照检查。

4. 第一周任务

Day 1 约定：Node 22 LTS；pnpm 9；编辑器开启 TypeScript + ESLint 实时检查。所有 demo 起手用 pnpm create vite@latest my-app -- --template react-ts，避免一开始就选 Next.js 把概念叠在一起。命令跑通后写进 notes/day1.md。

Day 7 步骤 A 只求 4 个功能：增、删、改状态、清空。步骤 B 补 4 类边界：空数组、标题 5000 字符、emoji/换行、localStorage 解析失败。每补一类都贴实际输出。

5. 阶段通用验收

1. 不看答案能复述每个 Hook 的依赖数组规则、stale closure 风险；
2. 用自己的话解释“为什么用 Context 但不直接 store 大对象”、“为什么 RQ 比手写 fetch 更省事”；
3. 画一张组件树 + 数据流图（父→子 props / 子→父 callback / Context / external store）；
4. 跑通生产构建（vite build / next build），无 warning；
5. 至少 3 组自定义数据并贴出实际渲染结果；
6. 关键路径有 profiling 截图（React DevTools Profiler / Lighthouse）；
7. 能修改已有应用（加功能、修 bug、调性能），而不是只能照抄。

6. 最终验收

• 独立完成：受控表单、自定义 Hook、Context + Reducer 替代小 Redux、Zustand 单一 store、TanStack Query 一个完整 query + mutation、React Router 一组嵌套路由、一种 SSR 框架（Next.js 或 Remix）跑通 prod build；
• 至少完成 12 个练习（含 4 个组件设计、4 个 Hook 习题、2 个 RQ 习题、2 个 SSR 习题）；
• 完成 1 个综合项目：完整电商 SPA（含路由、状态管理、SSR、测试、CI、监控），配套一份复盘；
• 能用 15 分钟讲清楚 React 18→19 关键变化（concurrent rendering、useTransition、Server Components、Actions）以及何时仍选 SPA。

7. 综合项目

首选：完整电商 SPA

• 路由：首页 / 商品列表 / 商品详情 / 购物车 / 结算 / 订单 / 登录 / 404；
• 状态：Zustand 管 UI（主题、侧栏），TanStack Query 管服务端数据，Context 只放鉴权；
• SSR：Next.js App Router；商品列表 SSG，详情 ISR，结算 CSR；
• 测试：RTL 单元 20+、Playwright e2e 5 路径、MSW 拦截 API；
• 可观测：Sentry 上报 + Web Vitals 上报 + OpenTelemetry trace；
• 部署：Vercel/Netlify 静态 + serverless functions；CI 跑 lint/typecheck/test/build。

备选：把现有 SPA 重构为 RSC + Server Actions 架构

• 保留原 SPA 路由和数据契约；
• 引入 App Router，把数据获取迁到 Server Component；
• 引入 Server Actions 替代部分 mutation；
• 输出一份“迁移前后 bundle / TTFB / LCP / 客户端 JS 体积”对比表。

任何项目都要包含：

1. 需求说明与角色（访客/登录用户/管理员）；
2. 状态管理选型理由；
3. 关键交互时序图；
4. 模块化源码（按 feature 切目录，组件 / hook / store / route / test 分离）；
5. 边界 / 异常测试；
6. 构建与部署说明；
7. README + 复盘报告（retrospective.md，含踩坑清单）。

8. 推荐开源资料

默认顺序：react.dev 主线 → 写 demo → Epic React 验错 → Patterns.dev 看模式 → 选栈查官方文档 → 写项目 → 复盘。复制代码前先看 LICENSE（默认 MIT）。

9. 学习资料汇聚（v0.3 自包含）

本节由本计划生成。链接指向原始材料或作者公开内容。生态变化快，决策时再查版本与日期。

9.1 背景与动机

React 2013 年由 Jordan Walke 在 Facebook 发布，最早为广告系统 UI 设计。2014 年公开。它的核心抽象是“UI = f(state)”：组件是函数、状态是输入、JSX 是声明式语法糖。

20152018 年间，Redux 与 class 生命周期成为默认套路。2019 年 Hooks 稳定后写法重写：useState / useEffect 取代 this.state / componentDidMount，函数组件成默认。20202023 年 Next.js 把 SSR / SSG 推回主流，Vite 把 dev server 拉回毫秒级。2024 年 React 19 引入 Server Components、Actions、useOptimistic、Web Vitals 内置优化。

今天 React 不只是 view library；它是“应用框架的基座”，围绕它的有数据获取、路由、样式、构建、测试、监控、a11y。学会 React 等于学会组织前端代码；上层框架按需选择。

9.2 概念地图

flowchart LR
  JSX[JSX] --> Component[函数组件]
  Component --> Props[props / children / composition]
  Component --> State[state]
  State --> Hook[Hooks]
  Hook --> Effect[useEffect / useLayoutEffect]
  Hook --> Transition[useTransition / useDeferredValue]
  Hook --> Reducer[useReducer]
  Reducer --> Context[Context]
  State --> External[External store: Zustand / Jotai / RTK]
  External --> ServerCache[TanStack Query]
  ServerCache --> Router[React Router / TanStack Router]
  Router --> Suspense[Suspense / ErrorBoundary]
  Component --> RSC[React Server Components]
  RSC --> ServerActions[Server Actions]
  Component --> Style[CSS Modules / Tailwind / Vanilla Extract]
  Component --> Test[Vitest / RTL / Playwright / MSW]
  Component --> Observe[Sentry / Web Vitals / OTel / DevTools]
  Component --> A11y[ARIA / 键盘 / 焦点管理]
  Component --> Build[Vite / Next.js / Remix]
  Build --> Deploy[Edge / Node / 静态]

关系说明：

• 组件 + JSX 是语法和组合层；
• Hooks 是状态与副作用的统一接口；
• 外部 store / Server cache 是规模化的两条轴：客户端状态 vs 服务端数据；
• Router 串起页面与数据；
• Suspense / ErrorBoundary 处理异步与失败；
• RSC 把组件的渲染推到服务端；
• Style、Test、Observe、A11y 是横切关注点。

9.3 基础知识讲解

9.3.1 论文 / 规范 / RFC

9.3.2 经典书籍

9.3.3 优秀博客 / 文档

9.3.4 核心人物

9.3.5 开发方法

重点 RFC 共 5 篇/组：

1. React Server Components RFC — 解释 RSC 为什么是“组件渲染在服务端、序列化结果给客户端”。
2. useTransition RFC — 解释并发渲染的入口与“低优先级更新”含义。
3. React 19 Actions RFC — 解释 useActionState / useFormStatus / Server Actions 的表单模型。
4. React 19 Release Notes（react.dev blog）— 总结新 Hook、优化、ref as prop 等。
5. Patterns.dev：React Server Components — 第三方对照讲清 RSC 与 SSR 区别。

补充：TanStack Query 的 staleTime / gcTime 文档、React Router 的 data router 说明、Next.js 的 partial prerendering 文档。

9.4 经典问题与经典案例

9.5 学习难点

概念难点

思维难点

工程难点

9.6 技术标准与接口

9.6.1 Entity

9.6.2 Scope

• React 定义组件模型、Hooks、并发渲染、Context、Suspense。
• React DOM / Native 负责渲染目标。
• RSC 改变“哪些代码在哪个环境跑”，是 React 19 的最大语义变化。
• JSX 不是 ECMAScript 标准；TypeScript / Babel / SWC 各自实现。
• React 自身不规定路由、状态、HTTP、样式、构建——这些是上层生态。

9.6.3 Structure

• 必须掌握：Component / props / state / useState / useEffect / useMemo / useCallback / useRef / useReducer / useContext / useTransition / useDeferredValue / useId / Suspense / ErrorBoundary / lazy / memo。
• React 19 新增：useActionState / useFormStatus / useOptimistic / use（读 Promise / Context）/ ref as prop。
• 关键概念：Server Component / Client Component / Server Action / boundary / hydration / streaming / partial prerendering。

9.6.4 Ecosystem

• 路由：React Router v6/v7、TanStack Router、Next.js App Router、Remix。
• 状态：Zustand、Jotai、Redux Toolkit、Valtio、Recoil（已停止维护）。
• 数据：TanStack Query、SWR、Apollo（GraphQL）。
• 样式：CSS Modules、Tailwind、styled-components、Emotion、Vanilla Extract、shadcn/ui。
• 构建：Vite、Next.js、Remix、Astro、Parcel、Rsbuild。
• 测试：Vitest、Jest、React Testing Library、Playwright、Cypress、MSW、Storybook。
• 可观测：Sentry、Web Vitals、OpenTelemetry、Datadog RUM、LogRocket、React DevTools。
• a11y：eslint-plugin-jsx-a11y、axe-core、@testing-library/jest-dom、Pa11y。
• 事实标准 vs 标准本身：默认选型（Vite + RR + Zustand + RQ + Vitest + RTL + Playwright + Sentry + Tailwind）不写在 React 文档，是社区共识。

9.6.5 Depth Tiers

本计划目标：综合项目阶段达到 L3，部分架构决策与 RSC 重构触及 L4。

9.6.6 Source

• react.dev：官方文档、版本说明。
• React Working Group 仓库 与 React 仓库：RFC 与实现。
• 引用快照：2026-07-30。React 19 已发布；RSC 在 Next.js App Router 中默认启用；新项目默认 react@19 / next@15。

10. 常见误区

• 把 useEffect 当万能胶水，初始 state 来自网络却用 effect 拉；
• 列表用 index 做 key，重排后状态错位；
• 用 Context 存高频更新（每次 dispatch 全部组件重渲染）；
• 用 Redux 存一切，不学 RQ；
• 路由用 hash 模式而不是 history，刷新无副作用但 SEO 差；
• 写受控表单但用 defaultValue + value 混用；
• 把 useMemo 当性能银弹，不 Profile 乱加；
• RQ 设 staleTime: 0 每次都打网络；
• SSR 直接 new Date() 或读 localStorage，造成 hydration mismatch；
• 把客户端代码放 Server Component，不加 'use client'；
• 用 <div onClick> 而非 <button>，丢掉 a11y；
• 上线后才接监控，错误盲跑；
• 框架选 Next.js 但又用 CRA 写法，不读 App Router；
• 不写测试就上线；
• 把“会写 demo”当“会做生产”，跳过监控 / a11y / 性能预算。

11. 所有知识点分类（统一规则）

1. 编程语言
2. 数据结构与算法
3. 计算机基础
4. 工程技术
5. Web 与后端
6. 前端与客户端
7. 数据与人工智能
8. 项目与职业能力
9. 安全与可靠性

本计划归属：前端与客户端 主 + 工程技术 辅。