Web 前端
Web 前端运行在不可控的浏览器与网络之上：解析 HTML、执行 JS、合成样式、处理输入与辅助功能。本篇以 React + TypeScript 为主要参照（与常见文档站、产品站一致），原则可迁移到其他框架。
平台分层（浏览器内）
| 层 | 关注点 | 笔记 |
|---|---|---|
| 文档 | 语义 HTML、SEO、渐进增强 | 先结构后样式 |
| 样式 | 布局、主题、响应式 | 设计 token、减少全局泄漏 |
| 行为 | 事件、状态、数据获取 | 边界处校验 API 响应 |
| 资产 | 图片、字体、代码分割 | 现代格式（AVIF/WebP）、loading=lazy |
React 应用结构（默认）
| 区域 | 职责 |
|---|---|
| 路由 | URL ↔ 视图；数据 loader 与错误边界 |
| 组件 | 展示 vs 容器；组合优于继承 |
| 状态 | 服务器状态 vs UI 状态分离 |
| 数据层 | fetch/RTK Query/React Query；缓存与失效策略 |
服务器状态（远程真相）：用查询库管理 stale time、重试、去重。
UI 状态（局部交互）：useState / context 小范围；避免全局 store 泛滥。
提示
默认数据流：父传 props，子回调上报；跨树用 context 或轻量 store；只有确需时才上全局状态库。
TypeScript 与 API 边界
- API 响应在边界用 schema 校验（zod、valibot）再进入组件树
- 组件 props 显式类型；列表项
key稳定 - 严格
tsconfig：strict,noUncheckedIndexedAccess（按项目渐进）
与 架构 · 边界 一致：不要把后端 DTO 形状泄漏到每一层组件。
性能清单
| 项 | 做法 |
|---|---|
| 首屏 | 路由级 code splitting、关键 CSS |
| 渲染 | 避免匿名内联函数导致子树重渲染；memo 有测量再用 |
| 列表 | 虚拟滚动（长列表） |
| 网络 | HTTP 缓存头、压缩、减少瀑布请求 |
| 图片 | 响应式 srcset、占位、LCP 优先 |
测量：Lighthouse、Web Vitals（LCP、INP、CLS）；真机 4G 抽样。
可访问性（a11y）
- 交互控件用原生元素或补全 role / 键盘 / 焦点
- 对比度与字号跟随系统（配合 指南 的写作清晰原则）
- 表单：
label关联、aria-invalid、错误文案可读 - 动效：尊重
prefers-reduced-motion
测试金字塔（前端）
| 层级 | 工具倾向 | 覆盖 |
|---|---|---|
| 单元 | Vitest/Jest + RTL | 纯函数、hook、小组件 |
| 集成 | RTL | 表单流、路由 |
| E2E | Playwright | 关键路径、跨浏览器抽样 |
CI 中 E2E 可 nightly，PR 跑冒烟子集——见 CI/CD。
与本知识库站点
本站基于 Docusaurus + React：MDX 即文档组件化；i18n 路径 /docs 与 /en/docs 分离。改主题或侧边栏时保持构建与英文镜像同步。