xiaoyu2er · xiaoyu2er · May 21, 2025 · May 21, 2025
diff --git a/apps/docs/content/zh-hans/docs/14/01-getting-started/index.mdx b/apps/docs/content/zh-hans/docs/14/01-getting-started/index.mdx
@@ -0,0 +1,6 @@
+---
+source-updated-at: 2025-05-16T04:52:11.000Z
+translation-updated-at: 2025-05-21T19:10:51.684Z
+title: 入门指南
+description: 学习如何使用 Next.js 创建全栈 Web 应用程序。
+---
diff --git a/apps/docs/content/zh-hans/docs/14/02-app/index.mdx b/apps/docs/content/zh-hans/docs/14/02-app/index.mdx
@@ -0,0 +1,74 @@
+---
+source-updated-at: 2025-05-16T04:52:11.000Z
+translation-updated-at: 2025-05-21T19:11:37.018Z
+title: 应用路由 (App Router)
+description: 在 Next.js 和 React 中使用最新的应用路由 (App Router) 功能，包括布局 (Layouts)、服务端组件 (Server Components)、Suspense 等特性。
+---
+
+Next.js 应用路由 (App Router) 引入了一种新的应用构建模式，支持 React 最新功能如 [服务端组件 (Server Components)](/docs/app/building-your-application/rendering/server-components)、[Suspense 流式渲染 (Streaming with Suspense)](/docs/app/building-your-application/routing/loading-ui-and-streaming#streaming-with-suspense) 和 [服务端操作 (Server Actions)](/docs/app/building-your-application/data-fetching/server-actions-and-mutations)。
+
+通过 [创建第一个页面](/docs/app/building-your-application/routing/pages-and-layouts) 开始使用应用路由 (App Router)。
+
+## 常见问题
+
+### 如何在布局中访问请求对象？
+
+出于设计考虑，您无法直接访问原始请求对象。但可以通过服务端专用函数访问 [`headers`](/docs/app/api-reference/functions/headers) 和 [`cookies`](/docs/app/api-reference/functions/cookies)。您也可以 [设置 cookies](#如何设置-cookies)。
+
+[布局 (Layouts)](/docs/app/building-your-application/routing/pages-and-layouts#layouts) 不会重新渲染。它们可以被缓存并在页面间导航时复用，以避免不必要的计算。通过限制布局访问原始请求，Next.js 可以防止在布局中执行可能影响性能的耗时用户代码。
+
+这种设计还确保了不同页面间布局行为的一致性和可预测性，简化了开发和调试流程。
+
+根据您构建的 UI 模式，[并行路由 (Parallel Routes)](/docs/app/building-your-application/routing/parallel-routes) 允许您在同一个布局中渲染多个页面，这些页面可以访问路由段和 URL 查询参数。
+
+### 如何在页面中访问 URL？
+
+默认情况下，页面是服务端组件 (Server Components)。您可以通过 [`params`](/docs/app/api-reference/file-conventions/page#params-optional) 属性访问路由段，通过 [`searchParams`](/docs/app/api-reference/file-conventions/page#searchparams-optional) 属性访问 URL 查询参数。
+
+如果使用客户端组件 (Client Components)，可以使用 [`usePathname`](/docs/app/api-reference/functions/use-pathname)、[`useSelectedLayoutSegment`](/docs/app/api-reference/functions/use-selected-layout-segment) 和 [`useSelectedLayoutSegments`](/docs/app/api-reference/functions/use-selected-layout-segments) 来处理更复杂的路由。
+
+此外，根据您构建的 UI 模式，[并行路由 (Parallel Routes)](/docs/app/building-your-application/routing/parallel-routes) 允许您在同一个布局中渲染多个页面，这些页面可以访问路由段和 URL 查询参数。
+
+### 如何从服务端组件重定向？
+
+您可以使用 [`redirect`](/docs/app/api-reference/functions/redirect) 将页面重定向到相对或绝对 URL。[`redirect`](/docs/app/api-reference/functions/redirect) 是临时重定向 (307)，而 [`permanentRedirect`](/docs/app/api-reference/functions/permanentRedirect) 是永久重定向 (308)。当在流式渲染 UI 时使用这些函数，它们会插入 meta 标签在客户端触发重定向。
+
+### 如何在应用路由中处理身份验证？
+
+以下是支持应用路由 (App Router) 的常见身份验证方案：
+
+- [NextAuth.js](https://next-auth.js.org/configuration/nextjs#in-app-router)
+- [Clerk](https://clerk.com/docs/quickstarts/nextjs)
+- [Lucia](https://lucia-auth.com/getting-started/nextjs-app)
+- [Auth0](https://github.com/auth0/nextjs-auth0#app-router)
+- [Stytch](https://stytch.com/docs/example-apps/frontend/nextjs)
+- [Kinde](https://kinde.com/docs/developer-tools/nextjs-sdk/)
+- 或手动处理会话或 JWT
+
+### 如何设置 cookies？
+
+您可以在 [服务端操作 (Server Actions)](/docs/app/building-your-application/data-fetching/server-actions-and-mutations#cookies) 或 [路由处理器 (Route Handlers)](/docs/app/building-your-application/routing/route-handlers) 中使用 [`cookies`](/docs/app/api-reference/functions/cookies) 函数设置 cookies。
+
+由于 HTTP 不允许在流式传输开始后设置 cookies，因此无法直接在页面或布局中设置 cookies。您也可以通过 [中间件 (Middleware)](/docs/app/building-your-application/routing/middleware#using-cookies) 设置 cookies。
+
+### 如何构建多租户应用？
+
+如果您需要构建一个服务于多个租户的 Next.js 应用，我们提供了 [示例项目](https://vercel.com/templates/next.js/platforms-starter-kit) 展示推荐架构。
+
+### 如何使应用路由缓存失效？
+
+Next.js 有多层缓存机制，因此有多种方式来使不同部分的缓存失效。[了解更多缓存机制](/docs/app/building-your-application/caching)。
+
+### 是否有基于应用路由的开源完整应用示例？
+
+有的。您可以查看 [Next.js Commerce](https://vercel.com/templates/next.js/nextjs-commerce) 或 [Platforms Starter Kit](https://vercel.com/templates/next.js/platforms-starter-kit)，这是两个使用应用路由 (App Router) 的大型开源示例。
+
+## 了解更多
+
+- [路由基础](/docs/app/building-your-application/routing)
+- [数据获取、缓存与重新验证](/docs/app/building-your-application/data-fetching/fetching-caching-and-revalidating)
+- [表单与数据变更](/docs/app/building-your-application/data-fetching/server-actions-and-mutations)
+- [缓存机制](/docs/app/building-your-application/caching)
+- [渲染基础](/docs/app/building-your-application/rendering)
+- [服务端组件](/docs/app/building-your-application/rendering/server-components)
+- [客户端组件](/docs/app/building-your-application/rendering/client-components)
diff --git a/apps/docs/content/zh-hans/docs/14/03-pages/index.mdx b/apps/docs/content/zh-hans/docs/14/03-pages/index.mdx
@@ -0,0 +1,10 @@
+---
+source-updated-at: 2025-05-16T04:52:11.000Z
+translation-updated-at: 2025-05-21T19:10:55.001Z
+title: 页面路由 (Pages Router)
+description: 在 Next.js 13 之前，页面路由 (Pages Router) 是通过直观的文件系统路由在 Next.js 中创建路由的主要方式。
+---
+
+在 Next.js 13 之前，页面路由 (Pages Router) 是 Next.js 中创建路由的主要方式。它采用直观的文件系统路由机制，将每个文件映射为一个路由。新版本的 Next.js 仍支持页面路由，但我们建议迁移至新的 [应用路由 (App Router)](/docs/app) 以利用 React 的最新特性。
+
+本部分文档适用于使用页面路由 (Pages Router) 的现有应用程序。
diff --git a/apps/docs/content/zh-hans/docs/14/04-architecture/accessibility.mdx b/apps/docs/content/zh-hans/docs/14/04-architecture/accessibility.mdx
@@ -0,0 +1,36 @@
+---
+source-updated-at: 2025-05-16T04:52:11.000Z
+translation-updated-at: 2025-05-21T19:11:18.052Z
+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/building-your-application/configuring/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` 标签添加 alt 文本、正确使用 `aria-*` 属性、正确使用 `role` 属性等。
+
+## 无障碍资源
+
+- [WebAIM WCAG 检查清单](https://webaim.org/standards/wcag/checklist)
+- [WCAG 2.2 指南](https://www.w3.org/TR/WCAG22/)
+- [A11y 项目](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/14/04-architecture/fast-refresh.mdx b/apps/docs/content/zh-hans/docs/14/04-architecture/fast-refresh.mdx
@@ -0,0 +1,58 @@
+---
+source-updated-at: 2025-05-16T04:52:11.000Z
+translation-updated-at: 2025-05-21T19:11:32.638Z
+title: 快速刷新 (Fast Refresh)
+description: 快速刷新 (Fast Refresh) 是一种热模块替换体验，可即时反馈您对 React 组件所做的编辑。
+---
+
+快速刷新 (Fast Refresh) 是 Next.js 的一项功能，可即时反馈您对 React 组件所做的编辑。在 **9.4 或更新版本** 的所有 Next.js 应用程序中，快速刷新默认启用。启用 Next.js 快速刷新后，大多数编辑内容应在 **不丢失组件状态** 的情况下 **一秒内可见**。
+
+## 工作原理
+
+- 如果您编辑 **仅导出 React 组件** 的文件，快速刷新将仅更新该文件的代码并重新渲染您的组件。您可以编辑该文件中的任何内容，包括样式、渲染逻辑、事件处理程序或副作用。
+- 如果您编辑包含 _非_ React 组件导出的文件，快速刷新将重新运行该文件及其导入该文件的其他文件。例如，如果 `Button.js` 和 `Modal.js` 都导入了 `theme.js`，编辑 `theme.js` 将更新这两个组件。
+- 最后，如果您编辑 **被 React 树之外的文件导入** 的文件，快速刷新 **将回退到完全重新加载**。您可能有一个文件既渲染 React 组件，又导出一个被 **非 React 组件** 导入的值。例如，您的组件可能还导出一个常量，而非 React 工具文件导入了它。在这种情况下，考虑将该常量迁移到单独的文件中，并在两个文件中导入它。这将重新启用快速刷新功能。其他情况通常可以用类似方式解决。
+
+## 错误恢复能力
+
+### 语法错误
+
+如果在开发过程中出现语法错误，您可以修复它并再次保存文件。错误将自动消失，因此您无需重新加载应用程序。**您不会丢失组件状态**。
+
+### 运行时错误
+
+如果您的错误导致组件内部出现运行时错误，您将看到一个上下文覆盖层。修复错误后，覆盖层将自动消失，无需重新加载应用程序。
+
+如果错误未发生在渲染期间，组件状态将被保留。如果错误发生在渲染期间，React 将使用更新后的代码重新挂载您的应用程序。
+
+如果您的应用程序中有 [错误边界](https://react.dev/reference/react/Component#catching-rendering-errors-with-an-error-boundary)（在生产环境中实现优雅降级的好方法），它们将在渲染错误后的下一次编辑时重试渲染。这意味着拥有错误边界可以防止您总是被重置到根应用状态。但请注意，错误边界不应 _过于_ 细化。React 在生产环境中使用它们，应始终有意设计。
+
+## 限制
+
+快速刷新会尝试保留您正在编辑的组件中的本地 React 状态，但仅在安全的情况下进行。以下是您可能会看到每次编辑文件时本地状态被重置的几个原因：
+
+- 类组件的本地状态不会被保留（仅函数组件和 Hooks 会保留状态）。
+- 您正在编辑的文件可能 _除了_ React 组件外还有其他导出。
+- 有时，文件会导出调用高阶组件（如 `HOC(WrappedComponent)`）的结果。如果返回的组件是类，其状态将被重置。
+- 匿名箭头函数如 `export default () => <div />;` 会导致快速刷新不保留本地组件状态。对于大型代码库，您可以使用我们的 [`name-default-component` codemod](/docs/pages/building-your-application/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`（依赖项）未更改，它也会重新运行。如果 React 不这样做，您的编辑将不会反映在屏幕上！
+
+有时，这可能导致意外结果。例如，即使 `useEffect` 具有空依赖项数组，在快速刷新期间仍会重新运行一次。
+
+然而，编写能够应对 `useEffect` 偶尔重新运行的代码是一种良好的实践，即使没有快速刷新也是如此。这将使您更容易在以后为其引入新的依赖项，并且 [React 严格模式](/docs/pages/api-reference/next-config-js/reactStrictMode) 也强制要求这一点，我们强烈建议启用它。
diff --git a/apps/docs/content/zh-hans/docs/14/04-architecture/index.mdx b/apps/docs/content/zh-hans/docs/14/04-architecture/index.mdx
@@ -0,0 +1,8 @@
+---
+source-updated-at: 2025-05-16T04:52:11.000Z
+translation-updated-at: 2025-05-21T19:10:52.434Z
+title: 架构
+description: Next.js 工作原理
+---
+
+了解 Next.js 的架构及其底层工作原理。