企业官网建设流程全解析

React 19 官方开发规范（完整版）

React 19 带来了编译器、Actions、Form 原生支持、Server Components、新 Hooks等重大特性，开发规范相比 React 18 有颠覆性更新。

这份规范是企业级、可直接落地的标准，覆盖：项目结构、代码风格、组件编写、 Hooks 、表单/ Actions、性能、TypeScript、最佳实践。

一、核心原则（React 19 必守）

1. 优先使用 React 19 原生能力，弃用旧方案
   • 表单：用原生<form action>+useActionState，弃用 Formik / React Hook Form（简单场景）
   • 数据获取：用use+ Suspense + Server Components，弃用冗余状态管理
   • 样式：优先 CSS Modules / Tailwind，禁止行内样式滥用
2. 组件必须纯函数化，无副作用、无隐式依赖
3. 服务端组件（RSC）默认化：能放服务端就不放客户端
4. 编译器优化优先，减少手动 memo
5. TypeScript 强制全量使用

二、项目目录规范（React 19 标准结构）

src/ ├── app/ # App Router 目录（Next.js / React 19 标准） │ ├── page.tsx # 页面入口（默认服务端组件） │ ├── layout.tsx # 根布局 │ ├── error.tsx # 错误边界 │ ├── loading.tsx # Suspense 加载 │ └── (routes)/ # 路由分组 ├── components/ # 公共组件 │ ├── ui/ # 基础 UI（Button、Input） │ ├── feature/ # 业务组件 │ └── client/ # 明确标记客户端组件 ├── lib/ # 工具函数、工具类 ├── actions/ # React 19 Server Actions ├── hooks/ // 自定义 Hooks ├── types/ # TS 类型定义 └── styles/ # 全局样式

强制规则

• 服务端组件：不要写 ‘use client’
• 客户端组件：必须在文件顶部声明 ‘use client’
• 所有页面默认服务端组件

三、代码风格规范

1. 命名规范

• 组件：大驼峰UserProfile.tsx
• 文件：与组件名一致UserProfile.tsx
• 函数/变量：小驼峰handleSubmit
• 常量：全大写+下划线MAX_RETRY_COUNT
• Server Actions：以action结尾submitFormAction
• 自定义 Hooks：以use开头useUserInfo

2. 格式规范

• 2 空格缩进
• 语句末尾必须加分号
• JSX 单标签自闭合<Input />
• 导入顺序：第三方库 → 公共组件 → 工具 → 样式
• 禁止死代码：未使用变量、import、函数必须清理

四、组件编写规范（React 19 核心）

1. 服务端组件（默认）

• 无状态、无 Hooks、无事件监听
• 直接获取数据、直接渲染
• 可嵌套客户端组件，但不能导入客户端组件的 Hooks

// app/page.tsx 默认服务端组件 import { getUserList } from '@/actions/userActions' export default async function HomePage() { const users = await getUserList() // 直接 await 获取数据 return <div>{users.map(user => <p key={user.id}>{user.name}</p>)}</div> }

2. 客户端组件（必须标记）

// components/client/LikeButton.tsx 'use client' // 强制第一行 import { useState } from 'react' export default function LikeButton() { const [like, setLike] = useState(false) return <button onClick={() => setLike(!like)}>{like ? '已赞' : '点赞'}</button> }

3. 组件定义规则

• 只使用箭头函数 / 函数声明，禁止 class 组件
• Props 必须用 TS 定义，必填/可选明确
• Props 解构使用，提高可读性
• 一个文件只导出一个默认组件
• 逻辑与 UI 分离：复杂组件拆分

type UserCardProps = { user: { id: string; name: string } onDelete?: (id: string) => void } export default function UserCard({ user, onDelete }: UserCardProps) { return ( <div className="card"> <h3>{user.name}</h3> {onDelete && <button onClick={() => onDelete(user.id)}>删除</button>} </div> ) }

4. 组件主体内不写DOM操作

因为每次数据状态改变刷新页面，都会执行组件函数。

五、React 19 Hooks 规范

1. Hooks 使用顺序固定，不嵌套、不条件执行

2. 优先使用 React 19 新 Hooks

• useActionState：表单状态
• useFormStatus：表单提交状态
• useOptimistic：乐观更新
• use：读取 Promise / 上下文

3. 禁用过时写法

• 弃用useState+useEffect获取数据
• 弃用手动管理 loading/error

4. 自定义 Hooks 规范

• 必须以use开头
• 内部只使用 Hooks
• 返回值清晰，使用数组或对象

// hooks/useUserInfo.ts 'use client' import { use } from 'react' import { fetchUser } from '@/actions/userActions' export function useUserInfo(userId: string) { const user = use(fetchUser(userId)) // React 19 use() return { user } }

六、React 19 表单与 Actions 规范（最重要）

React 19原生支持表单，彻底告别第三方库。

1. Server Actions 定义

// actions/userActions.ts 'use server' // 服务端 Action export async function updateUserAction(prevState: any, formData: FormData) { const name = formData.get('name') // 数据库操作 return { success: true, message: '保存成功' } }

2. 表单组件（客户端）

'use client' import { useActionState } from 'react' import { updateUserAction } from '@/actions/userActions' export default function UserForm() { // React 19 表单状态 const [state, formAction] = useActionState(updateUserAction, null) const { pending } = useFormStatus() // 提交状态 return ( <form action={formAction}> <input name="name" defaultValue="张三" /> <button disabled={pending} type="submit"> {pending ? '保存中...' : '保存'} </button> {state?.message && <p>{state.message}</p>} </form> ) }

3. 乐观更新（useOptimistic）

const [optimisticUsers, addOptimisticUser] = useOptimistic( users, (state, newUser) => [...state, newUser] )

七、数据获取规范（React 19）

1. 服务端组件：直接 await 获取数据
2. 客户端组件：使用 use() + Suspense
3. 禁止useEffect获取数据
4. 加载、错误使用loading.tsx/error.tsx

// 客户端数据获取 'use client' import { use, Suspense } from 'react' function UserData({ userId }: { userId: string }) { const user = use(fetchUser(userId)) return <div>{user.name}</div> } export default function UserPage() { return ( <Suspense fallback={<div>加载中...</div>}> <UserData userId="1" /> </Suspense> ) }

八、性能优化规范（React 19 编译器）

1. 优先 React 编译器自动优化，无需手动 memo
2. 禁止滥用memo/useMemo/useCallback
3. 列表必须加key，且不使用 index
4. 客户端组件尽量轻量化，大组件拆分为服务端+客户端

// 正确 key users.map(user => <User key={user.id} user={user} />) // 错误 key（禁止） users.map((user, idx) => <User key={idx} user={user} />)

九、TypeScript 强制规范

1. 所有组件、函数、变量必须定义类型
2. 禁止使用any，必须用unknown+ 类型守卫
3. Props、Actions 返回值必须定义接口
4. Server Actions 严格校验formData

type User = { id: string name: string age?: number // 可选 } type ActionState = { success: boolean message?: string } export async function updateUserAction( prevState: ActionState, formData: FormData ): Promise<ActionState> { return { success: true } }

十、禁止行为（红线规范）

1. 禁止在服务端组件使用'use client'、Hooks、事件
2. 禁止在客户端组件写耗时逻辑
3. 禁止useEffect充当数据请求
4. 禁止嵌套多层条件渲染导致难以维护
5. 禁止表单不使用action而用旧onSubmit
6. 禁止直接操作 DOM，一律用 React 方式

十一、Git / 提交规范

• feat: 新功能
• fix: 修复
• refactor: 重构
• style: 格式
• chore: 构建/工具
• docs: 文档

示例：

feat: add user list server component

总结（React 19 最核心 5 条）

1. 默认服务端组件，客户端必须标记 ‘use client’
2. 表单用 action + useActionState，弃用第三方库
3. 数据获取用 await / use()，禁止 useEffect
4. 靠 React 编译器优化，少用 memo
5. 全量 TypeScript，禁止 any