xiaoyu2er · xiaoyu2er · May 19, 2025 · May 19, 2025
diff --git a/apps/docs/content/zh-hans/docs/03-architecture/accessibility.mdx b/apps/docs/content/zh-hans/docs/03-architecture/accessibility.mdx
@@ -0,0 +1,36 @@
+---
+source-updated-at: 2025-05-16T04:52:11.000Z
+translation-updated-at: 2025-05-19T22:46:16.458Z
+title: 无障碍访问
+description: Next.js 内置的无障碍访问功能。
+---
+
+Next.js 团队致力于让所有开发者（及其终端用户）都能无障碍使用 Next.js。通过在 Next.js 中默认集成无障碍功能，我们旨在让互联网对每个人更加包容。
+
+## 路由播报
+
+当在服务端渲染的页面之间跳转时（例如使用 `<a href>` 标签），屏幕阅读器和其他辅助技术会在页面加载时播报页面标题，以便用户知晓页面已切换。
+
+除了传统的页面导航外，Next.js 还支持客户端转场以提升性能（使用 `next/link`）。为确保客户端转场也能被辅助技术播报，Next.js 默认内置了路由播报器。
+
+Next.js 路由播报器会依次检查 `document.title`、`<h1>` 元素和 URL 路径名，以确定要播报的页面名称。为提供最佳的无障碍用户体验，请确保应用中的每个页面都具有唯一且描述性的标题。
+
+## 代码检查
+
+Next.js 默认提供[集成的 ESLint 体验](/docs/pages/api-reference/config/eslint)，包括针对 Next.js 的自定义规则。默认情况下，Next.js 包含 `eslint-plugin-jsx-a11y` 插件，可帮助及早发现无障碍问题，包括对以下情况的警告：
+
+- [aria-props](https://github.com/jsx-eslint/eslint-plugin-jsx-a11y/blob/HEAD/docs/rules/aria-props.md?rgh-link-date=2021-06-04T02%3A10%3A36Z)
+- [aria-proptypes](https://github.com/jsx-eslint/eslint-plugin-jsx-a11y/blob/HEAD/docs/rules/aria-proptypes.md?rgh-link-date=2021-06-04T02%3A10%3A36Z)
+- [aria-unsupported-elements](https://github.com/jsx-eslint/eslint-plugin-jsx-a11y/blob/HEAD/docs/rules/aria-unsupported-elements.md?rgh-link-date=2021-06-04T02%3A10%3A36Z)
+- [role-has-required-aria-props](https://github.com/jsx-eslint/eslint-plugin-jsx-a11y/blob/HEAD/docs/rules/role-has-required-aria-props.md?rgh-link-date=2021-06-04T02%3A10%3A36Z)
+- [role-supports-aria-props](https://github.com/jsx-eslint/eslint-plugin-jsx-a11y/blob/HEAD/docs/rules/role-supports-aria-props.md?rgh-link-date=2021-06-04T02%3A10%3A36Z)
+
+例如，该插件可确保您为 `img` 标签添加替代文本、使用正确的 `aria-*` 属性、正确的 `role` 属性等。
+
+## 无障碍资源
+
+- [WebAIM WCAG 检查清单](https://webaim.org/standards/wcag/checklist)
+- [WCAG 2.2 指南](https://www.w3.org/TR/WCAG22/)
+- [The A11y Project](https://www.a11yproject.com/)
+- 检查前景与背景元素的[颜色对比度](https://developer.mozilla.org/docs/Web/Accessibility/Understanding_WCAG/Perceivable/Color_contrast)
+- 处理动画时使用 [`prefers-reduced-motion`](https://web.dev/prefers-reduced-motion/)
diff --git a/apps/docs/content/zh-hans/docs/03-architecture/fast-refresh.mdx b/apps/docs/content/zh-hans/docs/03-architecture/fast-refresh.mdx
@@ -0,0 +1,58 @@
+---
+source-updated-at: 2025-05-16T04:52:11.000Z
+translation-updated-at: 2025-05-19T22:46:30.445Z
+title: 快速刷新 (Fast Refresh)
+description: 快速刷新 (Fast Refresh) 是一种热模块替换 (HMR) 体验，能在您编辑 React 组件时提供即时反馈。
+---
+
+快速刷新 (Fast Refresh) 是 Next.js 集成的 React 功能，当您保存文件变更时，可以在保持客户端临时状态的同时实时重载浏览器页面。该功能在 **9.4 及以上版本** 的所有 Next.js 应用中默认启用。启用后，大多数编辑操作的效果都能在一秒内可见。
+
+## 工作原理
+
+- 如果您编辑的文件 **仅导出 React 组件**，快速刷新会仅更新该文件的代码并重新渲染对应组件。您可以修改该文件内的任何内容，包括样式、渲染逻辑、事件处理函数或副作用 (effects)。
+- 如果您编辑的文件包含 _非_ React 组件的导出，快速刷新会重新执行该文件及其所有导入文件。例如 `Button.js` 和 `Modal.js` 都导入了 `theme.js`，那么编辑 `theme.js` 会同时更新这两个组件。
+- 最后，如果您编辑的文件被 **React 组件树之外的文件导入**，快速刷新 **将回退为完全重载**。例如某个文件既渲染 React 组件，又导出一个被 **非 React 组件** 导入的值。这种情况下，建议将该常量迁移到独立文件，然后由原文件和工具文件共同导入。其他类似情况通常也可用相同方式解决。
+
+## 错误恢复能力
+
+### 语法错误
+
+开发过程中出现语法错误时，修复后再次保存文件即可。错误会自动消失，无需重载应用。**组件状态不会丢失**。
+
+### 运行时错误
+
+如果组件内发生运行时错误，会出现上下文错误遮罩。修复错误后遮罩会自动消失，无需重载应用。
+
+若错误未发生在渲染阶段，组件状态会被保留；若发生在渲染阶段，React 会使用更新后的代码重新挂载应用。
+
+如果应用中配置了 [错误边界 (Error Boundary)](https://react.dev/reference/react/Component#catching-rendering-errors-with-an-error-boundary)（这在生产环境中能实现优雅降级），渲染错误后的下一次编辑会触发重试渲染。这意味着错误边界可以避免应用状态总是重置到根状态。但请注意错误边界不应_过度_细分，它们在 React 生产模式中有特定用途，应当谨慎设计。
+
+## 限制
+
+快速刷新会尽量保留编辑组件的本地 React 状态，但仅在安全时生效。以下情况会导致文件编辑时本地状态被重置：
+
+- 类组件 (class components) 的状态不会被保留（仅函数组件和 Hooks 能保留状态）
+- 编辑的文件可能包含 React 组件之外的_其他_导出
+- 某些文件可能导出高阶组件 (HOC) 的调用结果如 `HOC(WrappedComponent)`，若返回的是类组件，其状态会被重置
+- 匿名箭头函数如 `export default () => <div />;` 会导致快速刷新无法保留组件状态。大型代码库可使用 [`name-default-component` 代码迁移工具](/docs/pages/guides/upgrading/codemods#name-default-component)
+
+随着代码库向函数组件和 Hooks 迁移，状态保留的覆盖率将提升。
+
+## 使用技巧
+
+- 快速刷新默认会保留函数组件（及 Hooks）的 React 本地状态
+- 有时您可能需要_强制_重置状态并重新挂载组件（例如调试仅会在挂载时触发的动画）。此时可在编辑文件中任意位置添加 `// @refresh reset` 指令。该指令仅作用于当前文件，会令快速刷新在每次编辑时重新挂载该文件定义的组件
+- 开发期间可在编辑的组件中添加 `console.log` 或 `debugger;`
+- 注意导入语句区分大小写。当导入路径与实际文件名不匹配时（如 `'./header'` 与 `'./Header'`），快速刷新和完全重载都可能失败
+
+## 快速刷新与 Hooks
+
+在可能的情况下，快速刷新会尝试保留组件状态。特别是 `useState` 和 `useRef` 会保留之前的值，只要不修改它们的参数或 Hooks 调用顺序。
+
+具有依赖项的 Hooks（如 `useEffect`、`useMemo` 和 `useCallback`）在快速刷新期间会_始终_更新，此时它们的依赖项数组会被忽略。
+
+例如将 `useMemo(() => x * 2, [x])` 编辑为 `useMemo(() => x * 10, [x])` 时，即使依赖项 `x` 未变化也会重新执行。若不如此，编辑结果就无法反映到界面上！
+
+有时这会导致意外结果，例如即使 `useEffect` 的依赖项数组为空，在快速刷新期间仍会执行一次。
+
+但编写能适应 `useEffect` 偶尔重新运行的代码是良好实践，这与是否使用快速刷新无关。这能方便后续添加新依赖项，也是我们强烈推荐的 [React 严格模式 (React Strict Mode)](/docs/pages/api-reference/config/next-config-js/reactStrictMode) 所要求的。
diff --git a/apps/docs/content/zh-hans/docs/03-architecture/index.mdx b/apps/docs/content/zh-hans/docs/03-architecture/index.mdx
@@ -0,0 +1,8 @@
+---
+source-updated-at: 2025-05-16T04:52:11.000Z
+translation-updated-at: 2025-05-19T22:45:46.888Z
+title: 架构
+description: Next.js 工作原理
+---
+
+深入了解 Next.js 的架构及其底层工作原理。