React on Liangweidong's blog

Vite 7 构建工具：从入门到 React / Vue / TypeScript 工程化实战

Tue, 15 Jul 2025 00:00:00 +0800

为什么写这篇：Vite 5+ 在 2023 年起成为新项目默认；Vite 6（2024-11）性能再次飞跃；Vite 7（2025-06）支持 Rolldown 实验性打包器。本文用最新 Vite 7 + React/Vue + TS 走通完整工程化流程，附带 monorepo 实战。

适用读者：要从 Webpack 迁到 Vite 的工程师；想给新项目选 Vite 的负责人；想用 Vite 7 最新特性（Rolldown / 环境变量）的中高级前端。

前置知识：会用 npm/pnpm；了解 React 或 Vue 基础；知道 TypeScript 是什么。

Vite 是什么
环境要求
创建 Vite 项目：5 种模板
项目结构详解
Vite 核心配置文件
TypeScript 集成
路径别名 @ 配置
反向代理与 HMR
多环境变量 .env 管理
生产构建：Rollup 与 Rolldown 实验
代码风格：ESLint + Prettier
VSCode 必装插件
Monorepo + pnpm workspace 实战
Vite vs Webpack 性能对比
常见排错

1. Vite 是什么

Vite（法语"快"的发音 /vit/）是下一代前端构建工具，由 Vue 作者尤雨溪团队开发。核心目标：让开发体验更快、更顺手。

1.1 核心特性

特性	说明
极速冷启动	开发模式不打包，按需 ESM 编译
毫秒级 HMR	修改文件只更新该模块，不重新加载页面
开箱即用 TS / JSX / CSS 预处理器	零配置支持
生产用 Rollup 打包	产物优化、Tree Shaking、代码分割
生态完整	Vue / React / Svelte / Solid / Preact 全支持
插件体系	兼容 Rollup 插件、自动兼容大多数 Webpack 插件

1.2 为什么快：传统 vs Vite

1
2
3
4
5
6
7


传统 Webpack 模式（dev）：
启动 ── 打包所有模块 ── 才能 serve

Vite 模式（dev）：
启动 ── 立即 serve ── 浏览器按需请求 ESM
 ↑
 浏览器原生 import 解析，服务器只编译被请求的文件

原理：现代浏览器都支持 <script type="module"> + 原生 ESM 导入。Vite 把"打包"这件事推迟到浏览器运行时——服务器只编译被请求的单个文件，完全跳过冷启动的全量打包。

2. 环境要求

工具	版本	备注
Node.js	20.19+ 或 22.12+	Vite 7 强制要求
pnpm（推荐）	9+	装包快、磁盘省
npm	10+	Node 自带
yarn	4+	Berry 系列

1
2


node -v # v20.19.0 或 v22.12.0+
pnpm -v # 9.x

不兼容旧 Node：Vite 7 不再支持 Node 18.x。

3. 创建 Vite 项目：5 种模板

3.1 命令行创建

1

pnpm create vite

交互式：

1
2
3
4
5


✔ Project name: … react-ts-demo1
✔ Select a framework: › React
✔ Select a variant: › TypeScript
✔ Use rolldown-vite (Experimental)?: no
✔ Install with pnpm and start now?: yes

跑完自动启动：

1
2
3
4
5


 VITE v7.2.7 ready in 339 ms

 ➜ Local: http://localhost:5173/
 ➜ Network: use --host to expose
 ➜ press h + enter to show help

3.2 直接指定模板

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


# React + TS
pnpm create vite react-ts-demo --template react-ts

# Vue 3 + TS
pnpm create vite vue3-ts-demo --template vue-ts

# Svelte
pnpm create vite svelte-demo --template svelte-ts

# 原生 JS
pnpm create vite vanilla-demo --template vanilla

# 列出所有模板
pnpm create vite --help

3.3 Rolldown-Vite 实验性选项

Vite 7 实验性接入 Rolldown——基于 Rust 的下一代打包器，目标是替换 esbuild + Rollup，实现极致构建速度。

问：Use rolldown-vite (Experimental)?: no → 目前不建议生产用
实验性质，可能与某些插件不兼容
实际收益：5-10x 打包速度提升（仅生产模式）

4. 项目结构详解

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


react-ts-demo1/
├── dist/ # 构建产物
├── node_modules/
├── public/ # 不参与构建的静态资源
│ └── vite.svg
├── src/
│ ├── assets/ # 静态资源（被 webpack/vite 处理）
│ │ └── react.svg
│ ├── components/ # 公共组件
│ ├── App.tsx # 根组件
│ ├── main.tsx # 入口
│ ├── App.css
│ ├── index.css # 全局样式入口
│ └── vite-env.d.ts # Vite 内置类型
├── .gitignore
├── eslint.config.js # ESLint 9 扁平配置
├── index.html # 入口 HTML
├── package.json
├── pnpm-lock.yaml # 必须提交
├── README.md
├── tsconfig.app.json # 应用代码 TS 配置
├── tsconfig.json # TS 根配置
├── tsconfig.node.json # Node 环境 TS 配置
└── vite.config.ts # Vite 配置

tsconfig 拆三份：Vite 模板默认把 TS 配置拆成 tsconfig.app.json（业务代码）和 tsconfig.node.json（vite.config.ts），用 references 关联。

5. Vite 核心配置文件

vite.config.ts：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41


import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react-swc'
import path from 'path'

export default defineConfig({
 plugins: [react()],

 resolve: {
 alias: {
 '@': path.resolve(__dirname, 'src')
 }
 },

 server: {
 port: 8080,
 host: '127.0.0.1',
 open: true,
 proxy: {
 '/api': {
 target: 'http://localhost:3000',
 changeOrigin: true,
 rewrite: (p) => p.replace(/^\/api/, '')
 }
 }
 },

 build: {
 target: 'es2020',
 sourcemap: false,
 outDir: 'dist',
 rollupOptions: {
 output: {
 manualChunks: {
 react: ['react', 'react-dom'],
 router: ['react-router-dom'],
 ui: ['antd']
 }
 }
 }
 }
})

6. TypeScript 集成

Vite 自动支持 .ts / .tsx / .vue 文件——不需要 ts-loader / babel-loader。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


// vite-env.d.ts
/// <reference types="vite/client" />

interface ImportMetaEnv {
 readonly VITE_APP_TITLE: string
 readonly VITE_API_BASE: string
}

interface ImportMeta {
 readonly env: ImportMetaEnv
}

读环境变量：

1
2
3


console.log(import.meta.env.VITE_API_BASE)
console.log(import.meta.env.MODE) // 'development' | 'production'
console.log(import.meta.env.DEV) // boolean

7. 路径别名 @ 配置

7.1 vite.config.ts

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


import { defineConfig } from 'vite'
import path from 'path'

export default defineConfig({
 resolve: {
 alias: {
 '@': path.resolve(__dirname, 'src')
 }
 }
})

7.2 tsconfig.json（必须配，否则 TS 找不到）

1
2
3
4
5
6
7
8


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

之后就能 import Foo from '@/components/Foo'。

8. 反向代理与 HMR

8.1 代理后端 API

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


server: {
 proxy: {
 '/api': {
 target: 'http://localhost:3000',
 changeOrigin: true,
 rewrite: (p) => p.replace(/^\/api/, '')
 },
 '/socket.io': {
 target: 'http://localhost:3000',
 ws: true, // 支持 WebSocket
 changeOrigin: true
 }
 }
}

8.2 HMR 配置

1
2
3
4
5
6
7


server: {
 hmr: {
 host: '127.0.0.1',
 port: 8080,
 overlay: true // 错误时全屏遮罩
 }
}

8.3 在 React 中接受 HMR

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


// main.tsx
import { StrictMode } from 'react'
import { createRoot } from 'react-dom/client'
import App from './App.tsx'

createRoot(document.getElementById('root')!).render(
 <StrictMode>
 <App />
 </StrictMode>
)

Vite 自动通过 import.meta.hot 注入 HMR API，不需要额外配置——React Fast Refresh 自动接管。

9. 多环境变量 .env 管理

Vite 默认只有 development 和 production。要扩展：

1
2
3
4


.env # 所有环境都加载
.env.development # npm run dev 加载
.env.test # npm run build --mode test 加载
.env.production # npm run build --mode production 加载

9.1 .env.development

1
2


VITE_APP_TITLE = '开发环境'
VITE_API_BASE = '/api'

9.2 .env.production

1
2


VITE_APP_TITLE = '生产环境'
VITE_API_BASE = 'https://api.example.com'

9.3 package.json scripts

1
2
3
4
5
6
7
8
9


{
 "scripts": {
 "dev": "vite",
 "build": "tsc -b && vite build",
 "build:test": "tsc --noEmit && vite build --mode test",
 "build:prod": "tsc --noEmit && vite build --mode production",
 "preview": "vite preview"
 }
}

必须 VITE_ 开头才能被 import.meta.env 识别——防止意外暴露服务端配置。

10. 生产构建：Rollup 与 Rolldown 实验

10.1 默认 Rollup 打包

1
2
3
4
5
6
7


pnpm build
# vite v7.2.7 building for production...
# ✓ 1234 modules transformed.
# dist/index.html 0.45 kB
# dist/assets/index-abc123.js 312.50 kB │ gzip: 102.40 kB
# dist/assets/index-def456.css 45.20 kB │ gzip: 12.10 kB
# ✓ built in 5.42s

10.2 关键选项

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


build: {
 target: 'es2020', // 目标浏览器
 outDir: 'dist',
 sourcemap: false, // 生产不开
 minify: 'esbuild', // 默认 esbuild，可换 terser
 cssCodeSplit: true, // CSS 拆分
 chunkSizeWarningLimit: 1500, // 块大小警告阈值
 rollupOptions: {
 output: {
 manualChunks: { /* 拆包 */ },
 entryFileNames: 'assets/[name].[hash].js',
 chunkFileNames: 'assets/[name].[hash].js',
 assetFileNames: 'assets/[name].[hash][extname]'
 }
 }
}

10.3 启用 Rolldown 实验

升级到 Vite 7 + 安装 Rolldown Vite：

1

pnpm add rolldown-vite -D

目前不建议生产用——某些插件还不兼容。

11. 代码风格：ESLint + Prettier

11.1 ESLint 9 扁平配置（vite create 自动生成）

eslint.config.js：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


import js from '@eslint/js'
import globals from 'globals'
import reactHooks from 'eslint-plugin-react-hooks'
import reactRefresh from 'eslint-plugin-react-refresh'
import tseslint from 'typescript-eslint'

export default tseslint.config(
 { ignores: ['dist'] },
 {
 extends: [js.configs.recommended, ...tseslint.configs.recommended],
 files: ['**/*.{ts,tsx}'],
 languageOptions: {
 ecmaVersion: 2020,
 globals: globals.browser
 },
 plugins: {
 'react-hooks': reactHooks,
 'react-refresh': reactRefresh
 },
 rules: {
 ...reactHooks.configs.recommended.rules,
 'react-refresh/only-export-components': 'warn'
 }
 }
)

11.2 Prettier

1

pnpm add -D prettier eslint-config-prettier

.prettierrc.json：

1
2
3
4
5
6
7
8


{
 "printWidth": 100,
 "tabWidth": 2,
 "semi": false,
 "singleQuote": true,
 "trailingComma": "all",
 "endOfLine": "auto"
}

12. VSCode 必装插件

插件	用途
ESLint	9+ 扁平配置支持
Prettier	自动格式化
TypeScript Vue Plugin (Volar)	Vue 3 + TS
ES7+ React/Redux snippets	React 代码片段
Tailwind CSS IntelliSense	Tailwind 类名补全
Path Intellisense	路径补全
Stylelint	CSS/Less/SCSS 检查

13. Monorepo + pnpm workspace 实战

13.1 pnpm-workspace.yaml

1
2
3


packages:
 - 'apps/*'
 - 'packages/*'

13.2 apps/web/package.json

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


{
 "name": "@myorg/web",
 "private": true,
 "scripts": {
 "dev": "vite",
 "build": "tsc -b && vite build"
 },
 "dependencies": {
 "@myorg/utils": "workspace:*",
 "@myorg/ui": "workspace:*"
 }
}

13.3 packages/utils/package.json

1
2
3
4
5
6
7
8
9


{
 "name": "@myorg/utils",
 "version": "1.0.0",
 "type": "module",
 "main": "./src/index.ts",
 "exports": {
 ".": "./src/index.ts"
 }
}

13.4 跨包引用

1
2
3


// apps/web/src/App.tsx
import { formatDate } from '@myorg/utils'
import { Button } from '@myorg/ui'

1
2
3


pnpm install # 装所有工作区依赖 + 链接
pnpm -F @myorg/web dev # 只跑 web 包的 dev
pnpm -r build # 所有包 build

14. Vite vs Webpack 性能对比

维度	Vite 7	Webpack 5
冷启动	< 1s（按需编译）	10-30s（全量打包）
HMR 速度	< 100ms	1-5s
生产构建	Rollup，5-15s	30s-2min
配置复杂度	零配置 + 少量 plugins	大量 loader + plugin
生态兼容	Rollup 插件 + 大量 Vite 插件	Webpack 生态（成熟）
SSR 支持	强（Vite SSR API）	中（webpack-ssr-plugin）
学习曲线	平缓	陡峭

2025 选型：

新项目：直接 Vite（启动快、配置简单）

老 Webpack 项目：不必强迁——Webpack 5 + 持久化缓存已经够快

大厂 monorepo：评估 Rspack（Rust 编写、Webpack 兼容 API）—— 字节跳动 + Microsoft 在用

15. 常见排错

15.1 TS2307: Cannot find module ‘./App.vue’

解法：建 src/vite-env.d.ts（Vite 模板已自动生成）：

1
2
3
4
5
6


/// <reference types="vite/client" />
declare module '*.vue' {
 import type { DefineComponent } from 'vue'
 const component: DefineComponent<{}, {}, any>
 export default component
}

15.2 import path 找不到

检查清单：

vite.config.ts 配了 alias
tsconfig.json 配了 paths（两端必须都配）
重启 VSCode（让 TS 服务重读 tsconfig）

15.3 代理 404

1
2
3
4
5
6
7


proxy: {
 '/api': {
 target: 'http://localhost:3000',
 changeOrigin: true,
 // rewrite: (p) => p.replace(/^\/api/, '') // ⚠️ 注释掉，看后端路由
 }
}

先看 dev server 真正发到哪——加 bypass: (req) => req.url 在 proxy 里打印。

15.4 端口被占用

1
2
3
4
5
6
7


# Windows
netstat -ano | findstr :8080
taskkill /PID <pid> /F

# macOS / Linux
lsof -i :8080
kill -9 <pid>

或改 Vite 配置：

1
2
3
4


server: {
 port: 8081, // 换个端口
 strictPort: false // 端口被占时自动换
}

小结

Vite 7 是 2025 年前端构建工具的"事实标准"：

极快冷启动（< 1s）—— 跳过 dev 模式的全量打包
TypeScript / JSX / CSS 预处理器零配置
@ 路径别名两行配置
多环境变量 .env.development / .env.production
生产 Rollup 打包，可选 Rolldown 实验（更快）
monorepo 配合 pnpm workspace 一行 pnpm -r build 跑所有包

下一步：学 Vite 插件开发（写自己的 plugin）、Vite SSR（配合 React 19 RSC / Vue 3 Nuxt）、微前端（Vite + Module Federation）。

参考资料

React 高级模式：HOC / Slot / Server Components / Actions 演进

Tue, 15 Apr 2025 00:00:00 +0800

为什么写这篇：React 的"组合（composition）“思想从 props 出发，演化出 HOC、Render Props、Slot、Compound Components 等模式；进入 React 19 又迎来 Server Components 与 Actions 的"服务端 + 异步"革命。本文是 React 高级模式的演进史。

适用读者：想深入理解 React 组件设计的中高级前端；准备面试 React 资深岗的工程师；要选型 RSC/SSR/CSR 架构的技术负责人。

前置知识：掌握 Hooks、JSX、组件生命周期。

1. React 组件设计的"组合"哲学

React 的核心设计原则之一是 “组合优于继承（composition over inheritance）”——UI 由小组件拼装成大组件，而不是用类继承扩展基类。

React 提供的组合工具从早到晚：

工具	时代	解决问题
props / children	全时代	最基础的"传值 + 插槽”
HOC（高阶组件）	2015-2019	跨组件复用逻辑（Hooks 出现前）
Render Props	2017-2020	函数式 children 传值
Hooks	2019+	函数组件的状态、副作用、复用
Compound Components	2018+	父组件 + 子组件隐式共享 state
Server Components	2023+	服务端渲染 + 零客户端 JS
Actions	2024+	声明式表单 + 异步操作

本文挑出 HOC、Slot、RSC、Actions 四个深入讲。

2. HOC：高阶组件

2.1 什么是 HOC

HOC 是一个函数，接收一个组件作为参数，返回一个新的组件——源自函数式编程的"高阶函数"。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


const withLogger = (WrappedComponent) => {
 return function NewComponent(props) {
 useEffect(() => {
 console.log(`${WrappedComponent.name} mounted`)
 }, [])
 return <WrappedComponent {...props} />
 }
}

// 用法
const UserPageWithLogger = withLogger(UserPage)

2.2 HOC 解决什么问题

场景	例子
逻辑复用	数据获取、订阅、权限控制、日志记录——多个组件都要
横切关注点	认证、i18n、主题切换——与业务无关但重复出现
Props 注入	注入 `currentUser` / `theme` / `i18n` 给所有被包装组件
渲染劫持	渲染前后添加元素、修改 props

2.3 经典案例：withAuth

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


function withAuth(WrappedComponent) {
 return function AuthenticatedComponent(props) {
 const { user, loading } = useAuth()

 if (loading) return <Spinner />
 if (!user) return <Navigate to="/login" />

 return <WrappedComponent {...props} user={user} />
 }
}

const DashboardPage = withAuth(Dashboard)

2.4 HOC 的优缺点

优点	缺点
复用逻辑，不修改原组件	嵌套地狱（5 层 HOC 包裹的组件调试噩梦）
隔离横切关注点	props 命名冲突（多个 HOC 注入同名 prop）
兼容老代码（class + function 都可包）	静态类型推断难（TypeScript 难判断返回组件的 props）

2.5 vs Hooks

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


// ❌ HOC：嵌套 3 层
const Enhanced = withAuth(withTheme(withI18n(UserPage)))

// ✅ 自定义 Hook：扁平化
function usePageContext() {
 const { user } = useAuth()
 const { theme } = useTheme()
 const { t } = useI18n()
 return { user, theme, t }
}

function UserPage() {
 const ctx = usePageContext()
 // ...
}

结论：Hooks 出现后，新项目基本不用 HOC。但维护老代码、与第三方库集成（如 redux 的 connect）时仍会见到。

3. Slot：插槽模式（内容分发）

3.1 什么是 Slot

Slot 允许父组件在子组件内部的"预定义位置"插入任意内容。Vue 有 <slot> 标签，Web Components 有 <slot name="header">，React 通过 children prop + 命名 prop 实现。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


// 经典：通用卡片
interface CardProps {
 title: string
 footer?: React.ReactNode
 children: React.ReactNode
}

function Card({ title, footer, children }: CardProps) {
 return (
 <div className="card">
 <h3>{title}</h3>
 <div className="card-body">{children}</div>
 {footer && <div className="card-footer">{footer}</div>}
 </div>
 )
}

// 用法
<Card
 title="用户信息"
 footer={<button>编辑</button>}
>
 <p>姓名：张三</p>
 <p>年龄：20</p>
</Card>

3.2 命名 Slot（多个插槽）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


interface LayoutProps {
 header: React.ReactNode
 sidebar: React.ReactNode
 children: React.ReactNode
}

function Layout({ header, sidebar, children }: LayoutProps) {
 return (
 <div className="layout">
 <header>{header}</header>
 <aside>{sidebar}</aside>
 <main>{children}</main>
 </div>
 )
}

// 用法
<Layout
 header={<TopNav />}
 sidebar={<SideMenu />}
>
 <PageContent />
</Layout>

3.3 Slot 的优势

优势	说明
灵活性	父组件完全控制插槽内容（文本 / JSX / 组件都可以）
职责分离	子组件管"外壳"，父组件管"内容"
可复用	通用 Layout/Card/Modal 都能这么写
避免 props 地狱	不用 10 个 props 传内容片段

3.4 条件 Slot

1
2
3
4
5
6
7
8
9


function Card({ title, children, showFooter, footer }) {
 return (
 <div>
 <h3>{title}</h3>
 {children}
 {showFooter && footer && <div>{footer}</div>}
 </div>
 )
}

4. RSC：React Server Components

4.1 什么是 RSC

React Server Components（RSC）是 React 19 引入的新范式——让组件可以只在服务端运行，零 JS 发送到客户端。

不是要"取代"客户端组件，而是"补充"：根据组件特性（是否需要交互、是否需要频繁更新、是否涉及敏感数据）选择在服务端还是客户端渲染。

4.2 三大痛点

痛点 1：客户端 JS 包体积巨大

1
2
3
4
5


传统 CSR：
- React + ReactDOM：140KB
- 状态管理库：50KB
- 业务代码 + 第三方库：500KB
- 全部 → 浏览器

RSC 把"无需交互"的服务端组件整个留在服务器——这部分代码和依赖永远不会到客户端。

痛点 2：低效的客户端数据获取

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


// ❌ 传统 CSR：useEffect 串行请求
function UserProfile({ id }) {
 const [user, setUser] = useState(null)
 useEffect(() => {
 fetch(`/api/users/${id}`).then(r => r.json()).then(setUser)
 }, [id])
 // 还要写 loading / error / cleanup...
}

// ✅ RSC：async 服务端组件
async function UserProfile({ id }) {
 const user = await db.user.findUnique({ where: { id } }) // 直接 DB
 return <div>{user.name}</div>
}

优势：

消除"瀑布式请求"——服务端并行取数
数据靠近数据源——直接调数据库
简化代码——不用 useState/useEffect/cleanup
减少网络延迟——不走 HTTP API

痛点 3：敏感信息暴露

CSR 模式下，所有 JS 都被发到浏览器——API key、数据库查询语句、SSO 回调 URL 全部可见。

RSC 把这些留在服务端——客户端只看到渲染后的 UI 描述。

4.3 RSC 的核心思想

“将渲染和数据获取的计算移动到最合适的地方——服务器，同时保持 React 组件模型的开发体验。”

5. 服务端组件 vs 客户端组件的边界

5.1 服务端组件（RSC）

维度	描述
运行环境	仅在服务端执行
JS 体积贡献	零（代码和依赖不会发到客户端）
能力	直接访问数据库、文件系统、内部 API、敏感操作
限制	不能用 `useState` / `useReducer` / `useEffect` / `useLayoutEffect`
限制	不能用浏览器 API（`window`、`document`）
限制	不能绑定 `onClick` / `onChange` 等事件
适用	静态内容、读 DB、读文件、保护敏感逻辑

5.2 客户端组件（RCC）

维度	描述
运行环境	客户端浏览器
JS 体积	完整 JS 包 + 依赖
能力	useState/useEffect/浏览器 API/事件处理
限制	不能直接调数据库 / 读文件系统
限制	不能直接 import 服务端组件
适用	表单、按钮、状态管理、WebSocket、地理位置

5.3 协作模式

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


// app/page.tsx (Next.js 14+ 默认 RSC)
import { db } from '@/lib/db'
import LikeButton from './LikeButton' // 客户端组件

// 服务端组件：直接读 DB
export default async function Page() {
 const post = await db.post.findFirst()

 return (
 <article>
 <h1>{post.title}</h1>
 <p>{post.content}</p>
 {/* 嵌套客户端组件——子组件的 RSC 部分仍是零 JS */}
 <LikeButton postId={post.id} initialCount={post.likes} />
 </article>
 )
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


// LikeButton.tsx
'use client' // ← 标记为客户端组件

import { useState } from 'react'

export default function LikeButton({ postId, initialCount }) {
 const [count, setCount] = useState(initialCount)
 return (
 <button onClick={async () => {
 setCount(c => c + 1) // 乐观更新
 await fetch(`/api/posts/${postId}/like`, { method: 'POST' })
 }}>
 ❤️ {count}
 </button>
 )
}

5.4 何时该用 RSC

1
2
3
4
5
6
7
8
9


问自己：这个组件需要用户交互吗？
├─ 否 → RSC（默认）
│
├─ 是（按钮点击 / 表单 / 动画 / 状态管理）
│ └─ 客户端组件（'use client'）
│
└─ 数据来源是？
 ├─ 数据库 / 文件系统 / 内部 API → RSC（直接在服务端取）
 └─ 第三方 API（用 useEffect）→ 客户端组件

黄金法则：默认所有组件都是 RSC，只有需要交互的才标 'use client'。

6. Actions API：声明式异步操作

6.1 传统痛点

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


// ❌ 传统表单：5 个 useState、3 个 effect、手动管理 loading/error
function OldForm() {
 const [title, setTitle] = useState('')
 const [loading, setLoading] = useState(false)
 const [error, setError] = useState(null)
 const [success, setSuccess] = useState(false)

 const handleSubmit = async (e) => {
 e.preventDefault()
 setLoading(true)
 setError(null)
 try {
 await fetch('/api/save', { method: 'POST', body: JSON.stringify({ title }) })
 setSuccess(true)
 } catch (e) {
 setError(e)
 } finally {
 setLoading(false)
 }
 }
 // ... 80 行
}

6.2 Actions：声明式解决

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


// ✅ React 19 Actions
async function saveAction(prevState, formData) {
 await fetch('/api/save', { method: 'POST', body: formData })
 return { ok: true }
}

function NewForm() {
 const [state, formAction, isPending] = useActionState(saveAction, { ok: false })
 return (
 <form action={formAction}>
 <input name="title" />
 <button disabled={isPending}>{isPending ? '保存中...' : '保存'}</button>
 {state.ok && <p>已保存</p>}
 </form>
 )
}

6.3 三个核心 Hook

1
2
3
4
5
6
7
8


// useActionState：表单状态封装
const [state, action, isPending] = useActionState(actionFn, initialState)

// useFormStatus：在表单内部组件中读父表单状态
const { pending, data, method } = useFormStatus()

// useOptimistic：乐观更新
const [optimisticState, addOptimistic] = useOptimistic(actualState, reducer)

6.4 乐观更新示例

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


async function addCommentAction(prev, formData) {
 const text = formData.get('text')
 // 模拟 API 慢
 await new Promise(r => setTimeout(r, 1000))
 return [...prev, { id: Date.now(), text }]
}

function Comments() {
 const [comments, dispatch, isPending] = useActionState(addCommentAction, [])
 const [optimistic, addOptimistic] = useOptimistic(comments)

 return (
 <form action={async (formData) => {
 addOptimistic({ id: Date.now(), text: formData.get('text') }) // 立即显示
 dispatch(formData) // 后台提交
 }}>
 <input name="text" />
 <button>提交</button>
 <ul>
 {optimistic.map(c => <li key={c.id}>{c.text}</li>)}
 </ul>
 </form>
 )
}

效果：用户提交评论立即显示，后台异步落库——体感零延迟。

7. 设计可复用、可维护组件的核心原则

7.1 单一职责原则（SRP）

一个组件只做一件事，并把它做好。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32


// ❌ 反例：UI + 数据 + 业务全在一个组件
function UserPage() {
 const [users, setUsers] = useState([])
 const [filter, setFilter] = useState('')
 useEffect(() => { fetch('/api/users').then(/* ... */) }, [])

 return (
 <div>
 <input value={filter} onChange={e => setFilter(e.target.value)} />
 <table>
 {users.filter(u => u.name.includes(filter)).map(u => (
 <tr key={u.id}><td>{u.name}</td><td>{u.email}</td></tr>
 ))}
 </table>
 </div>
 )
}

// ✅ 正例：拆分
function useUsers() { /* 数据获取 */ return { users, loading } }
function UserFilter({ value, onChange }) { return <input ... /> }
function UserTable({ users }) { return <table>...</table> }
function UserPage() {
 const { users } = useUsers()
 const [filter, setFilter] = useState('')
 return (
 <>
 <UserFilter value={filter} onChange={setFilter} />
 <UserTable users={users.filter(u => u.name.includes(filter))} />
 </>
 )
}

7.2 关注点分离（SoC）

层	职责
数据层	Redux / Zustand / React Query
逻辑层	自定义 Hook（封装业务规则）
视图层	纯函数组件（只负责渲染）
样式	CSS Modules / Tailwind / styled-components

7.3 松散耦合 & 高内聚

松散耦合：组件之间通过 props 通信，不用 ref 互相穿透
高内聚：相关逻辑（state + effect + render）放在一起，不要"散弹式修改"

7.4 封装

内部状态私有化（不暴露 setX 出去）
清晰的 props 接口（TypeScript interface 明确类型 + 必填/可选）
避免"泄露"内部实现（不要 props.children 之外传 DOM ref 出去）

7.5 实践清单

✅ 函数组件 + Hooks（不要 class）
✅ TypeScript 定义 props 接口
✅ camelCase 命名 prop、PascalCase 组件
✅ 区分受控/非受控组件
✅ 写测试（React Testing Library）
✅ 充分文档（Storybook）
✅ 考虑可访问性（A11y）：语义化 HTML、ARIA、键盘导航
✅ 性能意识：React.memo、useCallback、懒加载

8. 模式选型：什么时候用什么

场景	模式	例子
简单传值	props	`<Button color="red" />`
简单插槽	children	`<Card>任意内容</Card>`
多插槽	命名 prop	`<Layout header sidebar />`
跨组件复用逻辑	自定义 Hook	`useAuth()` / `useFetch()`
老的横切关注点	HOC（仅维护）	`withAuth` / `connect`
服务端取数 + 静态内容	RSC	博客文章页 / 列表页
表单 + 异步提交	Actions	评论框 / 登录 / 搜索
需要乐观更新	useOptimistic	点赞 / 收藏

新项目默认：

RSC（Next.js App Router）做骨架

客户端组件做交互

自定义 Hook 抽业务逻辑

复杂表单用 Actions

HOC 已成历史

小结

React 5 年的演进路径：

2015-2019：HOC 时代，class 组件 + HOC
2019-2024：Hooks 时代，函数组件 + 自定义 Hook
2024+：RSC + Actions 时代，服务端组件 + 声明式异步

新项目的默认架构：

服务端组件做 80% 的渲染
客户端组件只做交互
表单用 Actions
状态用 Hook + Zustand/Redux
跨组件逻辑用自定义 Hook

下一步：学 Next.js 14+ App Router——RSC + Actions 的生产级实践。或深入 React 19 Compiler——自动 memoization，让 React 性能优化"零成本"。

参考资料

React Hooks 完全指南：15 个核心 Hook 一网打尽

Mon, 15 Apr 2024 00:00:00 +0800

为什么写这篇：React Hooks 2019-02 在 16.8 正式发布，5 年内彻底改变了 React 的写法。从 useState 到 React 19 的 useActionState，Hooks 已经从"新特性"变成"默认写法"。本文按"开箱即用频次"梳理 15 个核心 Hook，给出核心概念、最佳实践与常见坑。

适用读者：刚学 React Hooks 的同学；想系统梳理 18/19 新 Hook 的中级工程师；从 class 组件迁过来的老 React。

前置知识：理解 JSX、函数组件、props。

Hooks 设计哲学
useState：状态管理基石
useReducer：复杂状态的"action + reducer"模式
useEffect：副作用与清理
useLayoutEffect：DOM 更新同步完成后立即执行
useContext：跨组件共享数据
useRef：DOM 引用与持久化数据
useImperativeHandle：自定义 ref 暴露的接口
useMemo & useCallback：缓存计算结果与函数引用
useDebugValue：自定义 Hook 在 DevTools 中的标签
useId：跨服务端/客户端的唯一 ID
useTransition：标记非紧急任务
React 19 新 Hook 速览
自定义 Hook：组合已有 Hook 复用逻辑
Hooks 三大规则

1. Hooks 设计哲学

Hooks 解决的核心问题：让函数组件拥有 class 组件的能力（state、生命周期、context），同时让代码更简洁、更好复用。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


// ❌ class 组件：逻辑散在生命周期里
class UserList extends React.Component {
 state = { users: [] }
 componentDidMount() {
 fetch('/api/users').then(r => r.json()).then(users => this.setState({ users }))
 }
 render() {
 return <ul>{this.state.users.map(u => <li>{u.name}</li>)}</ul>
 }
}

// ✅ 函数组件 + Hook：逻辑聚拢、可复用
function UserList() {
 const [users, setUsers] = useState([])
 useEffect(() => {
 fetch('/api/users').then(r => r.json()).then(setUsers)
 }, [])
 return <ul>{users.map(u => <li key={u.id}>{u.name}</li>)}</ul>
}

2. useState：状态管理基石

1

const [count, setCount] = useState(0)

2.1 初始值是函数（昂贵计算）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


function HeavyComputationComponent() {
 const expensiveInitialValue = () => {
 let sum = 0
 for (let i = 0; i < 1_000_000_000; i++) sum += i
 return sum % 100
 }
 // 函数只在首次渲染执行一次
 const [value, setValue] = useState(expensiveInitialValue)
 return <div>{value}</div>
}

2.2 函数式更新

1
2
3
4


function handleClickMultipleUpdates() {
 setCount(prev => prev + 1)
 setCount(prev => prev + 1) // 最终 count = 2（不是 1）
}

Why：React 18 的 setState 是批处理 + 异步的。连续调 3 次 setCount(c => c+1) 拿到的是"3 次累加后的 count"。

2.3 对象/数组不可变更新

1
2
3
4
5
6
7


const [user, setUser] = useState({ name: '张三', age: 20 })

// ✅ 正确：展开旧对象 + 改一个属性
setUser(prev => ({ ...prev, age: prev.age + 1 }))

const [items, setItems] = useState(['苹果', '香蕉'])
setItems(prev => [...prev, '橙子'])

直接修改原对象不会触发重渲染——React 用引用比较判断要不要更新。

3. useReducer：复杂状态的"action + reducer"模式

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


const initialState = { count: 0, step: 1 }

function reducer(state, action) {
 switch (action.type) {
 case 'increment': return { ...state, count: state.count + state.step }
 case 'decrement': return { ...state, count: state.count - state.step }
 case 'setStep': return { ...state, step: action.payload }
 default: throw new Error('unknown action')
 }
}

function Counter() {
 const [state, dispatch] = useReducer(reducer, initialState)
 return (
 <>
 Count: {state.count}
 <button onClick={() => dispatch({ type: 'increment' })}>+</button>
 <button onClick={() => dispatch({ type: 'setStep', payload: 5 })}>step=5</button>
 </>
 )
}

vs useState：state 之间有联动、依赖前一个 state、有多种"动作"时用 useReducer 更清晰。

4. useEffect：副作用与清理

1
2
3
4
5
6
7
8
9


useEffect(() => {
 // 副作用逻辑
 console.log('组件已渲染或依赖项已更新')

 return () => {
 // 可选：清理函数
 console.log('清理')
 }
}, [dep1, dep2])

4.1 三个常见用法

依赖项	行为
不传	每次渲染后都执行（通常不要）
`[]`	只在挂载/卸载时执行（一次）
`[a, b]`	`a` 或 `b` 变化时执行

4.2 清理函数：避免内存泄漏

1
2
3
4


useEffect(() => {
 const timer = setInterval(() => console.log('tick'), 1000)
 return () => clearInterval(timer) // 卸载时清理
}, [])

常见需要清理的场景：定时器、事件监听、网络请求（AbortController）、WebSocket、订阅。

4.3 AbortController 取消请求

1
2
3
4
5
6
7
8


useEffect(() => {
 const controller = new AbortController()
 fetch('/api/data', { signal: controller.signal })
 .then(r => r.json())
 .then(setData)
 .catch(e => { if (e.name !== 'AbortError') console.error(e) })
 return () => controller.abort()
}, [])

5. useLayoutEffect：DOM 更新同步完成后立即执行

1
2
3
4
5


useLayoutEffect(() => {
 // 同步执行，浏览器还没绘制
 ref.current.style.opacity = '0'
 // 立即读取布局相关数据
}, [data])

vs useEffect：

useEffect 异步，浏览器已绘制完才跑

useLayoutEffect 同步，DOM 更新完、浏览器重绘前立即跑

适用场景：读 DOM 布局（offsetHeight、scrollTop）、强制同步重排避免视觉抖动。

陷阱：服务端渲染（SSR）会发警告。建议优先用 useEffect，只有当出现"渲染闪烁"时才换 useLayoutEffect。

6. useContext：跨组件共享数据

解决 “props 透传"问题——避免一层层 <A><B><C>...</C></B></A> 手动传 props。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


// 1. 创建 Context
const ThemeContext = createContext({ theme: 'light', toggle: () => {} })

// 2. Provider 包裹
function App() {
 const [theme, setTheme] = useState('light')
 return (
 <ThemeContext.Provider value={{ theme, toggle: () => setTheme(t => t === 'light' ? 'dark' : 'light') }}>
 <Page />
 </ThemeContext.Provider>
 )
}

// 3. 子组件消费
function Button() {
 const { theme, toggle } = useContext(ThemeContext)
 return <button onClick={toggle}>{theme === 'light' ? '🌞' : '🌙'}</button>
}

坑：Context 的 value 每次渲染都是新对象，会让所有消费者重渲染。优化：用 useMemo 包装 value。

1
2


const value = useMemo(() => ({ theme, toggle }), [theme])
return <ThemeContext.Provider value={value}>...</ThemeContext.Provider>

7. useRef：DOM 引用与持久化数据

7.1 获取 DOM 引用

1
2
3
4
5
6
7
8
9


function TextInput() {
 const inputRef = useRef<HTMLInputElement>(null)

 useEffect(() => {
 inputRef.current?.focus() // 自动聚焦
 }, [])

 return <input ref={inputRef} />
}

7.2 持久化数据（不触发重渲染）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


function Timer() {
 const [count, setCount] = useState(0)
 const intervalRef = useRef<number | null>(null)

 const start = () => {
 intervalRef.current = window.setInterval(() => {
 setCount(c => c + 1)
 }, 1000)
 }

 const stop = () => {
 if (intervalRef.current) clearInterval(intervalRef.current)
 }

 return (
 <>
 <p>{count}s</p>
 <button onClick={start}>开始</button>
 <button onClick={stop}>停止</button>
 </>
 )
}

vs useState：改 ref.current 不触发 重渲染——适合"我需要存个值，但改了不更新 UI”。

8. useImperativeHandle：自定义 ref 暴露的接口

配合 forwardRef 使用，让父组件通过 ref 访问子组件的特定方法（隐藏内部实现）。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


const FancyInput = forwardRef((props, ref) => {
 const inputRef = useRef<HTMLInputElement>(null)

 useImperativeHandle(ref, () => ({
 focus: () => inputRef.current?.focus(),
 clear: () => { if (inputRef.current) inputRef.current.value = '' }
 }))

 return <input ref={inputRef} {...props} />
})

// 父组件
function Parent() {
 const ref = useRef<{ focus: () => void; clear: () => void }>(null)
 return (
 <>
 <FancyInput ref={ref} />
 <button onClick={() => ref.current?.focus()}>聚焦</button>
 <button onClick={() => ref.current?.clear()}>清空</button>
 </>
 )
}

Why：子组件自己决定暴露什么 API，父组件不需要知道内部 DOM 结构。

9. useMemo & useCallback：缓存计算结果与函数引用

9.1 useMemo：缓存"计算结果"

1
2
3


const expensiveValue = useMemo(() => {
 return data.reduce((sum, item) => sum + item.price * item.qty, 0)
}, [data]) // data 变才重算

9.2 useCallback：缓存"函数引用"

1
2
3
4
5
6
7
8


const handleClick = useCallback((id: string) => {
 setItems(items => items.filter(i => i.id !== id))
}, []) // 函数永远不重创建

// 子组件配合 React.memo
const Child = memo(function Child({ onClick, value }) {
 return <button onClick={() => onClick(value)}>click</button>
})

三者联动：useMemo 计算 + useCallback 传函数 + React.memo 阻止子组件重渲染——三件套只在大列表/复杂组件才有用。

常见误区：每个函数都包 useCallback——会拖慢性能（依赖比较也是开销）。只在该函数被传给 memo 化的子组件时才用。

10. useDebugValue：自定义 Hook 在 DevTools 中的标签

1
2
3
4
5
6


function useFriendStatus(friendID) {
 const [isOnline, setIsOnline] = useState(null)
 // ... 副作用逻辑
 useDebugValue(isOnline ? 'Online' : 'Offline')
 return isOnline
}

React DevTools → Components 面板里这个 Hook 会显示 Online / Offline，方便调试。

仅在 DevTools 中显示，生产环境不占成本（React 会自动移除）。

11. useId：跨服务端/客户端的唯一 ID

解决 SSR 的水合（hydration）问题——服务端和客户端的 ID 必须一致，否则 React 警告。

1
2
3
4
5
6
7
8
9


function PasswordField() {
 const id = useId() // :r0:
 return (
 <>
 <label htmlFor={id}>Password</label>
 <input id={id} type="password" />
 </>
 )
}

vs 自增 ID：Math.random() / Date.now() 在 SSR 下会不一致。

12. useTransition：标记非紧急任务

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


function Search({ data }) {
 const [isPending, startTransition] = useTransition()
 const [filter, setFilter] = useState('')

 const handleChange = (e) => {
 // 紧急任务：更新输入框（必须立即响应）
 setFilter(e.target.value)

 // 非紧急任务：过滤大列表（可被打断）
 startTransition(() => {
 setFilteredData(data.filter(d => d.name.includes(e.target.value)))
 })
 }

 return (
 <>
 <input value={filter} onChange={handleChange} />
 {isPending && <Spinner />}
 <List items={filteredData} />
 </>
 )
}

效果：用户输入时，输入框立即响应；过滤计算在后台进行（“transitioning”），避免页面卡顿。

13. React 19 新 Hook 速览

13.1 useActionState（替代 useState 表单提交）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


async function saveAction(prevState, formData) {
 await fetch('/api/save', { method: 'POST', body: formData })
 return { ok: true }
}

function Form() {
 const [state, formAction, isPending] = useActionState(saveAction, { ok: false })
 return (
 <form action={formAction}>
 <input name="title" />
 <button disabled={isPending}>{isPending ? '保存中...' : '保存'}</button>
 {state.ok && <p>已保存</p>}
 </form>
 )
}

省掉手写 useState({ loading, error, data }) 三个状态——React 自动管。

13.2 useFormStatus（读父表单的提交状态）

1
2
3
4


function SubmitButton() {
 const { pending, data, method } = useFormStatus()
 return <button disabled={pending}>{pending ? '...' : '提交'}</button>
}

13.3 useOptimistic（乐观更新）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


function Like({ likes, isLiked }) {
 const [optimistic, setOptimistic] = useOptimistic(isLiked)
 return (
 <button onClick={async () => {
 setOptimistic(true) // UI 立即显示已赞
 await fetch('/api/like', { method: 'POST' })
 // 接口成功后由父组件更新真实状态
 }}>
 {optimistic ? '❤️' : '🤍'} {likes}
 </button>
 )
}

Why：用户点"赞"后接口还没返回时，按钮已经变成红色——体感流畅 5 倍。

14. 自定义 Hook：组合已有 Hook 复用逻辑

自定义 Hook = 一个以 use 开头的函数，内部调用其他 Hook。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


// useLocalStorage.ts
function useLocalStorage<T>(key: string, initialValue: T) {
 const [value, setValue] = useState<T>(() => {
 const stored = localStorage.getItem(key)
 return stored ? JSON.parse(stored) : initialValue
 })

 useEffect(() => {
 localStorage.setItem(key, JSON.stringify(value))
 }, [key, value])

 return [value, setValue] as const
}

// 用法
function App() {
 const [theme, setTheme] = useLocalStorage<'light' | 'dark'>('theme', 'light')
 return <button onClick={() => setTheme(t => t === 'light' ? 'dark' : 'light')}>{theme}</button>
}

常见自定义 Hook：useFetch / useDebounce / useThrottle / usePagination / useModal / useWebSocket。

15. Hooks 三大规则

只能在函数组件顶层调用——不能在 if/for/嵌套函数里
只能在 React 函数中调用——函数组件、自定义 Hook；不能在普通 JS 函数里
useEffect 依赖项必须完整——配合 eslint-plugin-react-hooks 自动检查

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


// ❌ 错误：条件调用 Hook
function Bad() {
 if (count > 0) {
 const [v, setV] = useState(0) // 报错：Hook 数量不固定
 }
}

// ✅ 正确：永远在顶层调用
function Good() {
 const [v, setV] = useState(0)
 if (count > 0) {
 // 用 v 即可
 }
}

Why：React 用"调用顺序"识别每个 Hook（第一次是 useState、第二次是 useEffect…）。条件调用会破坏顺序，state 会错位。

小结

React Hooks 核心 15 个：

Hook	用途	React 版本
`useState`	状态管理基石	16.8+
`useReducer`	复杂状态	16.8+
`useEffect`	副作用	16.8+
`useLayoutEffect`	DOM 同步副作用	16.8+
`useContext`	跨组件共享	16.8+
`useRef`	DOM 引用 + 持久化数据	16.8+
`useImperativeHandle`	配合 forwardRef 暴露 API	16.8+
`useMemo` / `useCallback`	性能优化	16.8+
`useDebugValue`	DevTools 标签	16.8+
`useId`	SSR 唯一 ID	18+
`useTransition`	标记非紧急任务	18+
`useActionState`	表单状态管理	19+
`useFormStatus`	读表单状态	19+
`useOptimistic`	乐观更新	19+
`useDeferredValue`	延迟更新值	18+

下一步：学完 Hooks 之后，进阶性能优化（React.memo / 虚拟列表 / 代码分割）、状态管理（Redux Toolkit / Zustand / Jotai）、数据请求（React Query / SWR）、渲染模式（Suspense / Streaming SSR / Server Components）。

参考资料

Remotion 视频创作：React 写视频的工程化实践

Sat, 15 Feb 2020 00:00:00 +0800

什么是 Remotion

Remotion 是 2021 年起瑞典团队开发的 React 视频框架：用 React 组件描述视频帧，最后用 FFmpeg 渲染成 MP4。优势：

代码即视频：可以组件化、参数化、用 Git 版本管理
数据驱动：JSON 配置 → 自动生成几十条视频
AI 友好：搭配 LLM 生成文案 + 自动化脚本，几分钟产出可发布短视频

前置环境

Node.js 18+（推荐 22）
FFmpeg（Remotion 渲染依赖）
React 基础
一台能跑 Chrome 的电脑（Remotion Studio 用 Chrome preview）

创建项目

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


npx create-video@latest
# create-video@4.0.443
# Welcome to Remotion!

# 选择模板
# > Hello World 新手先用这个
# Next.js SaaS template
# Blank Nothing except an empty canvas
# Recorder A video production tool built entirely in JavaScript
# ...

按提示选：

Add TailwindCSS: yes
Add agent skills: yes（如果用 Claude Code 协作）
一路回车

用 IDEA 打开

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


# 装依赖
npm install

# 装 Studio CLI
npm i @remotion/cli

# 启动 Studio（默认 3000 端口）
npm dev
# 或
npx remotion studio

浏览器打开 http://localhost:3000，左侧是组件树，中间是时间线，右侧是实时预览。

渲染导出

1
2


# 渲染当前 Composition 为 MP4
npx remotion render out/HelloWorld.mp4

默认输出在 out/HelloWorld.mp4。

核心 API

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


import { useCurrentFrame, useVideoConfig, AbsoluteFill, Img, Audio, Sequence } from 'remotion';

export const HelloWorld = () => {
 const frame = useCurrentFrame();
 const { fps, durationInFrames, width, height } = useVideoConfig();

 return (
 <AbsoluteFill style={{ backgroundColor: 'white' }}>
 <h1 style={{
 fontSize: 80,
 textAlign: 'center',
 paddingTop: 200,
 color: frame > 30 ? 'red' : 'black',
 }}>
 第 {Math.round(frame / fps)} 秒
 </h1>
 </AbsoluteFill>
 );
};

useCurrentFrame() 返回当前帧号（从 0 开始），useVideoConfig() 返回 fps / 时长 / 宽高。AbsoluteFill 是定位容器。

关键概念

Composition：一段视频的元数据（fps、width、height、durationInFrames、组件）
Sequence：在指定时间区间内显示子组件
useCurrentFrame / useVideoConfig：读取当前播放状态
staticFile()：引用 public/ 下的静态资源

常用内置组件

组件	用途
`<AbsoluteFill>`	绝对定位全屏容器
`<Sequence from={30} durationInFrames={60}>`	1~3 秒显示子组件
`<Img src={staticFile('cover.png')} />`	显示图片
`<Audio src={staticFile('bgm.mp3')} />`	播放音频
`<Video src={staticFile('demo.mp4')} />`	播放视频
`<Series>`	多个 Sequence 串联

动画模式

弹簧物理（spring）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


import { spring, useCurrentFrame, useVideoConfig } from 'remotion';

const frame = useCurrentFrame();
const { fps } = useVideoConfig();

const scale = spring({
 frame,
 fps,
 config: { damping: 10, stiffness: 100, mass: 0.5 },
});

缓动（interpolate）

1
2
3
4


import { interpolate } from 'remotion';

const opacity = interpolate(frame, [0, 30, 60, 90], [0, 1, 1, 0]);
const translateY = interpolate(frame, [0, 30], [100, 0]);

数据驱动批量生成

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


// 配合 LLM 生成 JSON 数组
const videos = [
 { id: 'v1', title: '春节特辑', duration: 60 },
 { id: 'v2', title: '清明特辑', duration: 60 },
];

export const RemotionRoot = () => {
 return videos.map(v => (
 <Composition
 key={v.id}
 id={v.id}
 component={MyVideo}
 durationInFrames={v.duration * 30}
 fps={30}
 width={1080}
 height={1920}
 />
 ));
};

配合 Claude Code 写一个生成脚本：

1
2
3
4
5


# 调用 mmx-cli 生成文案 + TTS 配音
# 然后批量渲染
for id in v1 v2 v3; do
 npx remotion render "$id" "out/$id.mp4"
done

TailwindCSS 集成

1
2
3
4
5
6
7


# 创建项目时已经选了 TailwindCSS
# 组件里直接用
export const Card = () => (
 <AbsoluteFill className="bg-gradient-to-br from-purple-500 to-pink-500 flex items-center justify-center">
 <h1 className="text-6xl font-bold text-white">Hello</h1>
 </AbsoluteFill>
);

性能优化

减少状态：Remotion 渲染是逐帧的，组件内 React state 频繁变化会拖慢
避免 useEffect：用 useCurrentFrame 替代
静态资源：用 staticFile() 引用，Remotion 会在打包时复制
Chrome 远程调试：Studio 启动时加 --no-sandbox 在 Docker 里

常见问题

渲染卡死 / 内存溢出

1
2
3
4
5


# 加 --concurrency 限制并发
npx remotion render --concurrency=2

# 加 --jpeg-quality 降低质量换速度
npx remotion render --jpeg-quality=80

Windows FFmpeg 路径

1
2
3


# 把 C:\ffmpeg\bin 加到 PATH
# 或用 Scoop
scoop install ffmpeg

Linux 服务器无 GUI 渲染

1
2
3
4
5


# 装 headless Chrome
sudo apt install -y chromium-browser

# Remotion 自动用 headless Chrome
npx remotion render

进阶：Remotion + Vite 独立集成

不用 create-video 脚手架，把 Remotion 集成进现有 Vite 项目：

1

npm i @remotion/cli @remotion/renderer

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


// src/Root.tsx
import { Composition } from 'remotion';
import { MyVideo } from './MyVideo';

export const RemotionRoot = () => (
 <>
 <Composition
 id="MyVideo"
 component={MyVideo}
 durationInFrames={300}
 fps={30}
 width={1920}
 height={1080}
 />
 </>
);

1
2
3
4
5


// remotion.config.ts
import { Config } from '@remotion/cli/config';

Config.setVideoImageFormat('jpeg');
Config.setConcurrency(4);

下一步

想要 LLM 自动生成文案 + TTS 配音 + Remotion 渲染一条龙，看 mmx-cli 文档
想要 GitHub Action 自动渲染，看 https://www.remotion.dev/docs/ssr

参考资料

Remotion 官方：https://www.remotion.dev/docs
Remotion 中文文档：https://remotion-zh-cn-doc.vercel.app/
Remotion Gallery：https://www.remotion.dev/showcase

React 入门与 JSX 语法详解

Sat, 15 Oct 2016 00:00:00 +0800

为什么写这篇：2016 年 React 已经发布 4 年（v15.3 同期），Redux 单向数据流成为社区共识。理解 JSX 是理解 React 一切后续特性的基础——Hooks、Suspense、Server Components 全都建立在"JSX 描述 UI、React 把它变成真实 DOM"上。

适用读者：完全没接触过 React 的同学；从 Vue 迁过来的前端；想系统整理 React 基础的初中级工程师。

前置知识：HTML / CSS / JavaScript ES6+。

1. React 起源：组件化的胜利

在 React 出现之前，前端开发的"关注点分离"是按文件类型：

1
2
3


- index.html （结构）
- style.css （样式）
- app.js （行为）

这种模式在简单页面下很清晰。但随着应用变复杂：

同一个按钮的样式散落在多个 CSS 文件
一个交互逻辑跨多个 JS 文件
改一个页面要切 3 个文件

React 团队认为：渲染逻辑和 UI 的其他逻辑（事件处理、状态变化、数据展示）是紧密耦合的。强行把它们按文件分开，反而让代码散落、难以维护。

于是 React 提出"关注点分离的新方式"——按组件分：

1
2
3
4
5
6
7
8
9


src/
├── components/
│ ├── Button/
│ │ ├── Button.jsx # 这按钮的模板、样式、行为全在一起
│ │ ├── Button.module.css
│ │ └── Button.test.js
│ └── UserCard/
└── pages/
 └── Home/

每个组件是一个松耦合、可复用的单元——内部结构、样式、行为都聚拢在一起，组件之间通过 props 通信。

2. JSX 起源：UI 与逻辑的"反向"组合

JSX 是 React 团队把"组件化"哲学落到代码上的工具。JSX = JavaScript + XML 语法。

1

const element = <h1>Hello, world!</h1>

这行代码既不是字符串也不是 HTML——是JavaScript 表达式，最终会被 Babel/SWC 编译成 React.createElement('h1', null, 'Hello, world!')。

Why JSX：让你用写 HTML 的方式写 UI，但保留 JavaScript 全部能力（变量、函数、逻辑判断）。

3. JSX 5 大语法特性

3.1 在 JSX 中嵌入 JavaScript 表达式

用 {} 嵌入任何 JavaScript 表达式：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


const name = 'React 爱好者'
const element = <h1>Hello, {name}!</h1>

function formatName(user) {
 return user.firstName + ' ' + user.lastName
}

const user = { firstName: 'Harper', lastName: 'Perez' }
const greetingElement = (
 <h1>Hello, {formatName(user)}!</h1>
)

const sum = <div>{2 + 2}</div> // 4

只能放表达式，不能放语句：

1
2


{ var a = 1 } // ❌
{ if (ok) { ... } } // ❌

3.2 JSX 本身也是表达式

JSX 可以赋值给变量、作为函数参数、作为返回值：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


function getGreeting(user) {
 if (user) {
 return <h1>Hello, {user.name}!</h1>
 }
 return <h1>Hello, Stranger.</h1>
}

const welcomeMessage = getGreeting({ name: 'Alice' })

// 数组 + map 渲染列表
const items = ['Apple', 'Banana', 'Orange']
const listItems = (
 <ul>
 {items.map((item, index) => (
 <li key={index}>{item}</li>
 ))}
 </ul>
)

3.3 JSX 中的属性

JSX 属性用驼峰命名（camelCase），不是 HTML 那种小写连字符：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


// HTML: class / tabindex / onclick
// JSX : className / tabIndex / onClick

const element = (
 <a href="https://react.dev" target="_blank" className="my-link">
 React 官网
 </a>
)

const image = (
 <img
 src="avatar.jpg"
 alt="User Avatar"
 style={{ width: '100px', height: '100px' }}
 />
)

Why camelCase：JSX 最终编译成 JavaScript 对象，而 JavaScript 变量名不能用连字符。

HTML 属性	JSX 属性
`class`	`className`
`tabindex`	`tabIndex`
`for`	`htmlFor`
`readonly`	`readOnly`
`onclick`	`onClick`
`onchange`	`onChange`

3.4 JSX 子元素与 Fragment

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


// 多个元素必须包一个父元素
const container = (
 <div>
 <h1>标题</h1>
 <p>这是一段文字。</p>
 <img src="example.jpg" alt="示例图片" />
 </div>
)

// 用 Fragment 不增加 DOM 节点
const frag = (
 <>
 <p>第一段</p>
 <p>第二段</p>
 </>
)

Why Fragment：返回多个根节点时不污染 DOM 结构。<>...</> 是 <Fragment>...</Fragment> 的语法糖。

3.5 JSX 防注入攻击

1
2
3


const userInput = '<script>alert("hacked")</script>'
const safeElement = <div>{userInput}</div>
// 渲染为：<div>&lt;script&gt;alert("hacked")&lt;/script&gt;</div>

Why 安全：React 在渲染前会自动转义所有嵌入值——< 变 <，> 变 >，所有用户输入都安全。

4. 函数组件与 props

4.1 传统函数组件

1
2
3


function Welcome(props) {
 return <h1>Hello, {props.name}!</h1>
}

4.2 ES6 箭头函数

1
2
3


const Greeting = (props) => {
 return <p>Greetings, {props.name}!</p>
}

4.3 解构 props（推荐）

1
2
3
4
5
6
7
8


const UserInfo = ({ name, age }) => {
 return (
 <div>
 <p>Name: {name}</p>
 <p>Age: {age}</p>
 </div>
 )
}

4.4 接口定义 props（TypeScript，最推荐）

1
2
3
4
5
6
7


interface UserGreetProps {
 readonly isLog: boolean
}

function UserGreet({ isLog }: UserGreetProps) {
 return <h1>{isLog ? 'Logged in' : 'Logged out'}</h1>
}

4.5 必知：React 组件函数只能接一个 props 对象

1
2
3
4
5


// ❌ 错误——React 会传整个 props 对象，不是单个布尔值
function UserGreet(isLog: boolean) { }

// ✅ 正确
function UserGreet(props: { isLog: boolean }) { }

5. 特殊 prop：children

children 是组件内部的"插槽"——父组件传入的所有 JSX 都通过 children 拿到。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


// components/Layout.tsx
import React from 'react'

interface LayoutProps {
 readonly title: string
 readonly children?: React.ReactNode
}

function Layout({ title, children }: LayoutProps) {
 return (
 <div style={{ border: '10px solid #eee', padding: '20px' }}>
 <h1>{title}</h1>
 <div>{children}</div>
 </div>
 )
}

export default Layout

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


// App.tsx
import Layout from './components/Layout'

function App() {
 return (
 <Layout title="用户管理系统">
 <p>这是应用的主要内容。</p>
 <button>点击我</button>
 </Layout>
 )
}

实际效果：title 是 prop，children 是 prop 的特殊形式——React 把 <p>...</p><button>...</button> 整个打包成 children 数组传给 Layout。

6. 条件渲染：&& 与三元运算符

6.1 && 短路运算

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


function Mailbox(props) {
 const unreadMessages = props.unreadMessages
 return (
 <div>
 <h1>Hello!</h1>
 {unreadMessages.length > 0 &&
 <h2>您有 {unreadMessages.length} 条未读消息。</h2>
 }
 </div>
 )
}

原理：A && B 当 A 为 true 时返回 B；当 A 为 false 时返回 A（React 忽略 false / null / undefined）。

6.2 三元运算符

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


function Greeting(props) {
 return (
 <div>
 {props.isLoggedIn
 ? <h1>欢迎回来！</h1>
 : <h1>请先登录。</h1>
 }
 </div>
 )
}

vs if/else：三元表达式可以在 JSX 中内联。if/else 必须提到 JSX 之外。

6.3 阻止组件渲染

1
2
3
4
5
6


function WarningBanner(props) {
 if (!props.warn) {
 return null // 渲染空——不显示任何东西
 }
 return <div className="warning">警告！</div>
}

return null 不会卸载组件——生命周期（包括 Hooks）仍会调用。

7. 列表渲染与 key 的正确用法

7.1 基础列表

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


function NumberList(props) {
 const numbers = props.numbers
 const listItems = numbers.map((number) => (
 <li key={number.toString()}>{number}</li>
 ))
 return <ul>{listItems}</ul>
}

const numbers = [1, 2, 3, 4, 5]
<NumberList numbers={numbers} />

7.2 key 的作用

key 是 React 用于识别列表中每个元素的特殊字符串属性。当列表项顺序变化或增删时，key 帮助 React 高效更新 DOM——避免不必要的重新创建。

7.3 key 的选择

1
2
3
4
5
6


// ✅ 用数据里的稳定唯一 ID
const todos = [{ id: 't1', text: '吃饭' }, { id: 't2', text: '睡觉' }]
todos.map(t => <li key={t.id}>{t.text}</li>)

// ❌ 避免用 index（除非列表完全静态，永不变化）
todos.map((t, i) => <li key={i}>{t.text}</li>)

Why 避免 index 当 key：当你在列表头部插入一条新数据，所有 index 都会 +1，React 误以为"所有项都变了"——性能暴跌，还可能引发输入框焦点错位、动画异常等 bug。

8. JSX 工具链：VSCode 插件与转换器

8.1 VSCode 必装插件

插件	用途
ES7+ React/Redux/React-Native snippets	`rfc` / `rcc` / `useState` 等代码片段
ESLint	代码规范
Prettier	自动格式化
Auto Rename Tag	改开始标签自动改结束标签
Codeium（或 GitHub Copilot）	AI 补全

常用代码片段前缀：

前缀	展开为
`rfc`	function 组件
`rcc`	class 组件
`useState`	`const [val, setVal] = useState(0)`
`useEffect`	`useEffect(() => {}, [])`
`imr`	`import React from 'react'`

8.2 浏览器插件

React Developer Tools（Chrome / Firefox 扩展）—— 装上后 DevTools 多两个 Tab：Components（看组件树和 props）和 Profiler（看组件渲染性能）。

8.3 HTML ↔ JSX 转换器

transform.tools/html-to-jsx——把 HTML 片段粘进去，自动转 JSX（自动加 className、闭合自闭合标签等）。

8.4 入门教程

VSCode 官方 React 教程——30 分钟跑通第一个 React 应用。

9. 实用资源

9.1 文档

React 官方中文文档：zh-hans.react.dev
React 官方英文文档：react.dev

9.2 学习路径

JSX + 函数组件（本文）
状态管理：useState / useReducer
副作用：useEffect / useLayoutEffect
组件通信：Props / Context / 状态管理库
性能优化：memo / useMemo / useCallback
高级特性：Suspense / ErrorBoundary / Server Components

小结

React 入门核心：

设计哲学：UI 与逻辑聚拢在"组件"里，组件之间通过 props 通信
JSX：HTML-like 语法 + JS 能力，编译成 React.createElement 调用
JSX 5 大特性：表达式嵌入、属性 camelCase、Fragment、children、auto-escape
函数组件 + props：现代 React 的"最小单位"
条件渲染：&& 短路、三元表达式、return null
列表渲染 + key：永远用稳定 ID 当 key，绝不用 index

下一步：学 Hooks（useState / useEffect / useContext / useReducer）——这是 React 16.8+ 引入的"函数式组件能力扩展"，是现代 React 一切的基础。读懂 Hooks 后，再学状态管理（Redux / Zustand）、路由（React Router）、数据请求（React Query / SWR）就水到渠成。

React on Liangweidong's blog

Vite 7 构建工具：从入门到 React / Vue / TypeScript 工程化实战

目录

1. Vite 是什么

1.1 核心特性

1.2 为什么快：传统 vs Vite

2. 环境要求

3. 创建 Vite 项目：5 种模板

3.1 命令行创建

3.2 直接指定模板

3.3 Rolldown-Vite 实验性选项

4. 项目结构详解

5. Vite 核心配置文件

6. TypeScript 集成

7. 路径别名 @ 配置

7.1 vite.config.ts

7.2 tsconfig.json（必须配，否则 TS 找不到）

8. 反向代理与 HMR

8.1 代理后端 API

8.2 HMR 配置

8.3 在 React 中接受 HMR

9. 多环境变量 .env 管理

9.1 .env.development

9.2 .env.production

9.3 package.json scripts

10. 生产构建：Rollup 与 Rolldown 实验

10.1 默认 Rollup 打包

10.2 关键选项

10.3 启用 Rolldown 实验

11. 代码风格：ESLint + Prettier

11.1 ESLint 9 扁平配置（vite create 自动生成）

11.2 Prettier

12. VSCode 必装插件

13. Monorepo + pnpm workspace 实战

13.1 pnpm-workspace.yaml

13.2 apps/web/package.json

13.3 packages/utils/package.json

13.4 跨包引用

14. Vite vs Webpack 性能对比

15. 常见排错

15.1 TS2307: Cannot find module ‘./App.vue’

15.2 import path 找不到

15.3 代理 404

15.4 端口被占用

小结

参考资料

React 高级模式：HOC / Slot / Server Components / Actions 演进

目录

1. React 组件设计的"组合"哲学

2. HOC：高阶组件

2.1 什么是 HOC

2.2 HOC 解决什么问题

2.3 经典案例：withAuth

2.4 HOC 的优缺点

2.5 vs Hooks

3. Slot：插槽模式（内容分发）

3.1 什么是 Slot

3.2 命名 Slot（多个插槽）

3.3 Slot 的优势

3.4 条件 Slot

4. RSC：React Server Components

4.1 什么是 RSC

4.2 三大痛点

痛点 1：客户端 JS 包体积巨大

痛点 2：低效的客户端数据获取

痛点 3：敏感信息暴露

4.3 RSC 的核心思想

5. 服务端组件 vs 客户端组件的边界

5.1 服务端组件（RSC）

5.2 客户端组件（RCC）

5.3 协作模式

5.4 何时该用 RSC

6. Actions API：声明式异步操作

6.1 传统痛点

6.2 Actions：声明式解决

6.3 三个核心 Hook

6.4 乐观更新示例

7. 设计可复用、可维护组件的核心原则

7.1 单一职责原则（SRP）

7.2 关注点分离（SoC）