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 new file mode 100644 index 00000000..a9eee415 --- /dev/null +++ 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 应用程序。 +--- \ No newline at end of file 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 new file mode 100644 index 00000000..d3e7fb69 --- /dev/null +++ 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) \ No newline at end of file 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 new file mode 100644 index 00000000..76ea0a87 --- /dev/null +++ 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) 的现有应用程序。 \ No newline at end of file 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 new file mode 100644 index 00000000..d4c31cf9 --- /dev/null +++ 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 中默认集成无障碍功能，我们旨在让互联网对每个人更加包容。 + +## 路由播报 + +当在服务端渲染的页面之间跳转时（例如使用 `` 标签），屏幕阅读器和其他辅助技术会在页面加载时播报页面标题，让用户感知页面已切换。 + +除了传统的页面导航方式外，Next.js 还支持客户端转场以提升性能（使用 `next/link`）。为确保客户端转场也能被辅助技术播报，Next.js 默认内置了路由播报器。 + +Next.js 路由播报器会依次检查 `document.title`、`

` 元素和 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/) \ No newline at end of file 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 new file mode 100644 index 00000000..434acc20 --- /dev/null +++ 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 () =>
;` 会导致快速刷新不保留本地组件状态。对于大型代码库，您可以使用我们的 [`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) 也强制要求这一点，我们强烈建议启用它。 \ No newline at end of file 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 new file mode 100644 index 00000000..12c2faca --- /dev/null +++ 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 的架构及其底层工作原理。 \ No newline at end of file diff --git a/apps/docs/content/zh-hans/docs/14/04-architecture/nextjs-compiler.mdx b/apps/docs/content/zh-hans/docs/14/04-architecture/nextjs-compiler.mdx new file mode 100644 index 00000000..119603a4 --- /dev/null +++ b/apps/docs/content/zh-hans/docs/14/04-architecture/nextjs-compiler.mdx @@ -0,0 +1,311 @@ +--- +source-updated-at: 2025-05-16T04:52:11.000Z +translation-updated-at: 2025-05-21T19:12:11.737Z +title: Next.js 编译器 +description: Next.js 编译器采用 Rust 编写，用于转换和压缩您的 Next.js 应用。 +--- + +Next.js 编译器采用 Rust 编写并使用 [SWC](https://swc.rs/)，能够为生产环境转换和压缩 JavaScript 代码。它取代了 Babel 的单文件转换和 Terser 的压缩打包功能。 + +自 Next.js 12 版本起，该编译器的编译速度比 Babel 快 17 倍且默认启用。如果您的应用已有 Babel 配置或使用了[不支持的功能](#不支持的功能)，则会自动回退使用 Babel。 + +## 为什么选择 SWC？ + +[SWC](https://swc.rs/) 是一个基于 Rust 的可扩展平台，为下一代快速开发者工具而生。 + +SWC 可用于编译、压缩、打包等场景，并支持功能扩展。您可以通过它执行代码转换（内置或自定义），这些转换由 Next.js 等高层工具触发。 + +选择 SWC 的原因包括： + +- **可扩展性**：SWC 可作为 Crate 嵌入 Next.js，无需分叉库或规避设计限制 +- **性能**：切换至 SWC 后，Next.js 实现了快 3 倍的热更新和快 5 倍的构建，仍有优化空间 +- **WebAssembly**：Rust 对 WASM 的支持使其能覆盖所有平台 +- **社区生态**：Rust 社区和生态系统蓬勃发展 + +## 支持的功能 + +### Styled Components + +我们正在将 `babel-plugin-styled-components` 移植到 Next.js 编译器。 + +首先升级到最新版 Next.js：`npm install next@latest`，然后更新 `next.config.js`： + +```js filename="next.config.js" +module.exports = { + compiler: { + styledComponents: true, + }, +} +``` + +高级用法可配置具体参数： + +> 注意：`minify`、`transpileTemplateLiterals` 和 `pure` 暂未实现，进度可追踪[此 issue](https://github.com/vercel/next.js/issues/30802)。服务端渲染 (SSR) 和 `displayName` 转换是使用 `styled-components` 的核心需求。 + +```js filename="next.config.js" +module.exports = { + compiler: { + // 配置选项详见 https://styled-components.com/docs/tooling#babel-plugin + styledComponents: { + // 开发模式默认启用，生产模式默认禁用以减小体积 + displayName?: boolean, + // 默认启用 + ssr?: boolean, + // 默认启用 + fileName?: boolean, + // 默认空数组 + topLevelImportPaths?: string[], + // 默认为 ["index"] + meaninglessFileNames?: string[], + // 默认启用 + cssProp?: boolean, + // 默认空字符串 + namespace?: string, + // 暂不支持 + minify?: boolean, + // 暂不支持 + transpileTemplateLiterals?: boolean, + // 暂不支持 + pure?: boolean, + }, + }, +} +``` + +### Jest + +Next.js 编译器可转译测试代码，并简化 Jest 配置： + +- 自动模拟 `.css`、`.module.css`（及其 `.scss` 变体）和图片导入 +- 使用 SWC 自动设置 `transform` +- 将 `.env` 文件加载到 `process.env` +- 忽略 `node_modules` 和 `.next` 目录 +- 读取 `next.config.js` 中的实验性 SWC 标志 + +升级后配置 `jest.config.js`： + +```js filename="jest.config.js" +const nextJest = require('next/jest') + +// 指定 Next.js 应用路径以加载配置 +const createJestConfig = nextJest({ dir: './' }) + +// 自定义 Jest 配置 +const customJestConfig = { + setupFilesAfterEnv: ['/jest.setup.js'], +} + +// 异步导出确保能加载 Next.js 配置 +module.exports = createJestConfig(customJestConfig) +``` + +### Relay + +启用 [Relay](https://relay.dev/) 支持： + +```js filename="next.config.js" +module.exports = { + compiler: { + relay: { + // 需与 relay.config.js 一致 + src: './', + artifactDirectory: './__generated__', + language: 'typescript', + eagerEsModules: false, + }, + }, +} +``` + +> **注意**：Next.js 将 `pages` 目录下所有 JavaScript 文件视为路由。因此 `relay-compiler` 的 `artifactDirectory` 必须配置在 `pages` 外，否则生成的文件会被误认为路由导致构建失败。 + +### 移除 React 属性 + +用于移除 JSX 属性（常用于测试），类似 `babel-plugin-react-remove-properties`。 + +移除默认正则匹配 `^data-test` 的属性： + +```js filename="next.config.js" +module.exports = { + compiler: { + reactRemoveProperties: true, + }, +} +``` + +移除自定义属性： + +```js filename="next.config.js" +module.exports = { + compiler: { + // 正则语法基于 Rust，与 JavaScript 不同 + reactRemoveProperties: { properties: ['^data-custom$'] }, + }, +} +``` + +### 移除 console + +移除应用代码中所有 `console.*` 调用（不包括 `node_modules`），类似 `babel-plugin-transform-remove-console`。 + +移除全部 `console.*`： + +```js filename="next.config.js" +module.exports = { + compiler: { + removeConsole: true, + }, +} +``` + +保留 `console.error`： + +```js filename="next.config.js" +module.exports = { + compiler: { + removeConsole: { + exclude: ['error'], + }, + }, +} +``` + +### 传统装饰器 + +Next.js 会自动检测 `jsconfig.json` 或 `tsconfig.json` 中的 `experimentalDecorators` 配置（常用于旧版 `mobx` 等库）。 + +此功能仅为兼容旧应用，新项目不建议使用。 + +升级后更新配置文件： + +```js +{ + "compilerOptions": { + "experimentalDecorators": true + } +} +``` + +### importSource + +自动应用 `jsxImportSource` 配置（常用于 [Theme UI](https://theme-ui.com) 等库）。 + +升级后更新配置文件： + +```js +{ + "compilerOptions": { + "jsxImportSource": "theme-ui" + } +} +``` + +### Emotion + +正在移植 `@emotion/babel-plugin` 到 Next.js 编译器。 + +升级后配置 `next.config.js`： + +```js filename="next.config.js" +module.exports = { + compiler: { + emotion: boolean | { + // 生产构建默认禁用 + sourceMap?: boolean, + // 默认为 'dev-only' + autoLabel?: 'never' | 'dev-only' | 'always', + // 默认为 '[local]' + labelFormat?: string, + // 自定义导入映射 + importMap?: { + [packageName: string]: { + [exportName: string]: { + canonicalImport?: [string, string], + styledBaseImport?: [string, string], + } + } + }, + }, + }, +} +``` + +### 代码压缩 + +自 v13 起默认使用 SWC 压缩器，速度比 Terser 快 7 倍。 + +如需切换回 Terser： + +```js filename="next.config.js" +module.exports = { + swcMinify: false, +} +``` + +### 模块转译 + +自动转译本地包（如 monorepo）或外部依赖（`node_modules`），取代 `next-transpile-modules` 包。 + +```js filename="next.config.js" +module.exports = { + transpilePackages: ['@acme/ui', 'lodash-es'], +} +``` + +### 模块化导入 + +此功能已在 Next.js 13.5 中被 [`optimizePackageImports`](/docs/app/api-reference/next-config-js/optimizePackageImports) 取代，建议升级使用无需手动配置的新方案。 + +## 实验性功能 + +### SWC 性能分析 + +生成符合 [trace event 格式](https://docs.google.com/document/d/1CvAClvFfyA5R-PhYUmn5OOQtYMH4h6I0nSsKchNAySU/preview)的分析文件： + +```js filename="next.config.js" +module.exports = { + experimental: { + swcTraceProfiling: true, + }, +} +``` + +生成的 `swc-trace-profile-${timestamp}.json` 文件可用 Chrome 开发者工具或 [speedscope](https://www.speedscope.app/) 查看。 + +### SWC 插件（实验性） + +通过 WASM 插件自定义转换行为： + +```js filename="next.config.js" +module.exports = { + experimental: { + swcPlugins: [ + [ + 'plugin', + { + ...pluginOptions, + }, + ], + ], + }, +} +``` + +`swcPlugins` 接受插件路径（npm 包名或 .wasm 文件绝对路径）和配置对象组成的元组数组。 + +## 不支持的功能 + +当项目存在 `.babelrc` 文件时，Next.js 会自动回退使用 Babel 进行文件转换，以确保与现有自定义 Babel 插件的兼容性。 + +如果您有特殊 Babel 配置，[欢迎分享](https://github.com/vercel/next.js/discussions/30174)。我们正在移植常用 Babel 转换功能，未来将支持插件系统。 + +## 版本历史 + +| 版本 | 变更 | +| --------- | ---------------------------------------------------------------------------------------------------- | +| `v13.1.0` | [模块转译](https://nextjs.org/blog/next-13-1#built-in-module-transpilation-stable) 和 [模块化导入](https://nextjs.org/blog/next-13-1#import-resolution-for-smaller-bundles) 稳定化 | +| `v13.0.0` | 默认启用 SWC 压缩器 | +| `v12.3.0` | SWC 压缩器[稳定版](https://nextjs.org/blog/next-12-3#swc-minifier-stable)发布 | +| `v12.2.0` | 新增 [SWC 插件](#swc-插件实验性) 实验性支持 | +| `v12.1.0` | 新增 Styled Components、Jest、Relay、移除 React 属性、传统装饰器、移除 console 和 jsxImportSource 支持 | +| `v12.0.0` | 正式推出 [Next.js 编译器](https://nextjs.org/blog/next-12) | \ No newline at end of file diff --git a/apps/docs/content/zh-hans/docs/14/04-architecture/supported-browsers.mdx b/apps/docs/content/zh-hans/docs/14/04-architecture/supported-browsers.mdx new file mode 100644 index 00000000..b2674c0a --- /dev/null +++ b/apps/docs/content/zh-hans/docs/14/04-architecture/supported-browsers.mdx @@ -0,0 +1,68 @@ +--- +source-updated-at: 2025-05-16T04:52:11.000Z +translation-updated-at: 2025-05-21T19:11:20.166Z +title: 支持的浏览器 +description: Next.js 的浏览器支持情况及所支持的 JavaScript 功能特性。 +--- + +Next.js **开箱即用支持现代浏览器**，无需额外配置。 + +- Chrome 64+ +- Edge 79+ +- Firefox 67+ +- Opera 51+ +- Safari 12+ + +## Browserslist + +如需针对特定浏览器或功能进行适配，Next.js 支持在 `package.json` 文件中配置 [Browserslist](https://browsersl.ist)。默认情况下 Next.js 使用以下 Browserslist 配置： + +```json filename="package.json" +{ + "browserslist": [ + "chrome 64", + "edge 79", + "firefox 67", + "opera 51", + "safari 12" + ] +} +``` + +## Polyfills + +我们自动注入了[广泛使用的 polyfills](https://github.com/vercel/next.js/blob/canary/packages/next-polyfill-nomodule/src/index.js)，包括： + +- [**fetch()**](https://developer.mozilla.org/docs/Web/API/Fetch_API) — 替代方案：`whatwg-fetch` 和 `unfetch` +- [**URL**](https://developer.mozilla.org/docs/Web/API/URL) — 替代方案：[`url` 包 (Node.js API)](https://nodejs.org/api/url.html) +- [**Object.assign()**](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object/assign) — 替代方案：`object-assign`、`object.assign` 和 `core-js/object/assign` + +如果您的任何依赖项包含这些 polyfills，它们将在生产构建中被自动移除以避免重复。 + +此外，为减少打包体积，Next.js 只会为需要这些 polyfills 的浏览器加载它们。全球大部分网络流量都不会下载这些 polyfills。 + +### 自定义 Polyfills + +如果您的代码或任何外部 npm 依赖需要目标浏览器不支持的功能（如 IE 11），您需要自行添加 polyfills。 + +这种情况下，您应该在[自定义 ``](/docs/pages/building-your-application/routing/custom-app) 或具体组件中为**所需特定 polyfill** 添加顶层导入。 + +## JavaScript 语言特性 + +Next.js 允许您直接使用最新的 JavaScript 特性。除 [ES6 特性](https://github.com/lukehoban/es6features)外，Next.js 还支持： + +- [Async/await](https://github.com/tc39/ecmascript-asyncawait) (ES2017) +- [对象展开/剩余属性](https://github.com/tc39/proposal-object-rest-spread) (ES2018) +- [动态 `import()`](https://github.com/tc39/proposal-dynamic-import) (ES2020) +- [可选链](https://github.com/tc39/proposal-optional-chaining) (ES2020) +- [空值合并](https://github.com/tc39/proposal-nullish-coalescing) (ES2020) +- [类字段](https://github.com/tc39/proposal-class-fields) 和 [静态属性](https://github.com/tc39/proposal-static-class-features) (ES2022) +- 以及更多！ + +### TypeScript 特性 + +Next.js 内置 TypeScript 支持。[了解更多](/docs/pages/building-your-application/configuring/typescript)。 + +### 自定义 Babel 配置（高级） + +您可以自定义 Babel 配置。[了解更多](/docs/pages/building-your-application/configuring/babel)。 \ No newline at end of file diff --git a/apps/docs/content/zh-hans/docs/14/04-architecture/turbopack.mdx b/apps/docs/content/zh-hans/docs/14/04-architecture/turbopack.mdx new file mode 100644 index 00000000..ce915d65 --- /dev/null +++ b/apps/docs/content/zh-hans/docs/14/04-architecture/turbopack.mdx @@ -0,0 +1,64 @@ +--- +source-updated-at: 2025-05-16T04:52:11.000Z +translation-updated-at: 2025-05-21T19:11:26.000Z +title: Turbopack +description: Turbopack 是一个专为 JavaScript 和 TypeScript 优化的增量式打包工具，采用 Rust 编写，并内置于 Next.js 中。 +--- + +[Turbopack](https://turbo.build/pack) (测试版) 是一个专为 JavaScript 和 TypeScript 优化的增量式打包工具，采用 Rust 编写，并内置于 Next.js 中。 + +## 使用方法 + +Turbopack 可在 Next.js 的 `pages` 和 `app` 目录中使用，以加速本地开发。要启用 Turbopack，请在运行 Next.js 开发服务器时使用 `--turbo` 标志。 + +```json filename="package.json" highlight={3} +{ + "scripts": { + "dev": "next dev --turbo", + "build": "next build", + "start": "next start", + "lint": "next lint" + } +} +``` + +## 支持的功能 + +Next.js 中的 Turbopack 对大多数用户来说无需配置，并可扩展以满足更高级的用例。要了解 Turbopack 当前支持的功能，请查看 [API 参考文档](/docs/app/api-reference/next-config-js/turbo)。 + +## 不支持的功能 + +Turbopack 目前仅支持 `next dev`，不支持 `next build`。我们正在努力实现对构建的支持，以逐步迈向稳定版本。 + +当前不支持以下功能： + +- `next.config.js` 中的 [`webpack()`](/docs/app/api-reference/next-config-js/webpack) 配置 + - Turbopack 替代了 Webpack，这意味着不支持 Webpack 配置。 + - 要配置 Turbopack，[请参阅文档](/docs/app/api-reference/next-config-js/turbo)。 + - Turbopack 支持部分 [Webpack 加载器](/docs/app/api-reference/next-config-js/turbo#webpack-loaders)。 +- Babel (`.babelrc`) + - Turbopack 使用 [SWC](/docs/architecture/nextjs-compiler#why-swc) 编译器进行所有转译和优化。这意味着默认不包含 Babel。 + - 如果您有 `.babelrc` 文件，可能不再需要它，因为 Next.js 包含了常见的 Babel 插件作为可启用的 SWC 转换。您可以在 [编译器文档](docs/architecture/nextjs-compiler#supported-features) 中了解更多信息。 + - 如果确认您的特定用例未被覆盖后仍需使用 Babel，可以利用 Turbopack 的 [自定义 Webpack 加载器支持](/docs/app/api-reference/next-config-js/turbo#webpack-loaders) 来包含 `babel-loader`。 +- 在 App Router 中自动创建根布局。 + - 目前不支持此行为，因为它会更改输入文件，相反，会显示错误提示您手动在所需位置添加根布局。 +- `@next/font` (旧版字体支持)。 + - `@next/font` 已弃用，推荐使用 `next/font`。[`next/font`](/docs/app/building-your-application/optimizing/fonts) 在 Turbopack 中完全支持。 +- `new Worker('file', import.meta.url)`。 + - 我们计划在未来实现此功能。 +- [Relay 转换](/docs/architecture/nextjs-compiler#relay) + - 我们计划在未来实现此功能。 +- `experimental.nextScriptWorkers` + - 我们计划在未来实现此功能。 +- [AMP](/docs/pages/building-your-application/configuring/amp)。 + - 目前不计划在 Next.js 中通过 Turbopack 支持 AMP。 +- Yarn PnP + - 目前不计划在 Next.js 中通过 Turbopack 支持 Yarn PnP。 +- [`experimental.urlImports`](/docs/app/api-reference/next-config-js/urlImports) + - 目前不计划在 Next.js 中通过 Turbopack 支持 `experimental.urlImports`。 + +## 生成追踪文件 + +追踪文件允许 Next.js 团队调查并改进性能指标和内存使用情况。要生成追踪文件，请在 `next dev --turbo` 命令后追加 `NEXT_TURBOPACK_TRACING=1`，这将生成 `.next/trace.log` 文件。 + +在报告与 Turbopack 性能和内存使用相关的问题时，请在 [GitHub](https://github.com/vercel/next.js) 问题中包含追踪文件。 \ No newline at end of file diff --git a/apps/docs/content/zh-hans/docs/14/05-community/index.mdx b/apps/docs/content/zh-hans/docs/14/05-community/index.mdx new file mode 100644 index 00000000..4282401f --- /dev/null +++ b/apps/docs/content/zh-hans/docs/14/05-community/index.mdx @@ -0,0 +1,33 @@ +--- +source-updated-at: 2025-05-16T04:52:11.000Z +translation-updated-at: 2025-05-21T19:11:04.520Z +title: Next.js 社区 +nav_title: 社区 +description: 参与 Next.js 社区互动。 +--- + +Next.js 每周下载量超过 500 万次，拥有遍布全球的庞大开发者社区。以下是参与我们社区的方式： + +## 贡献代码 + +您可以通过以下几种方式为 Next.js 的发展做出贡献： + +- [文档](/docs/community/contribution-guide)：提出改进建议或撰写新章节，帮助用户理解如何使用 Next.js +- [示例项目](https://github.com/vercel/next.js/tree/canary/contributing/examples)：通过创建新示例或改进现有示例，帮助开发者将 Next.js 与其他工具和服务集成 +- [代码库](https://github.com/vercel/next.js/tree/canary/contributing/core)：了解底层架构，参与错误修复，并提出新功能建议 + +## 讨论交流 + +如果您有关于 Next.js 的问题，或希望帮助他人，欢迎随时加入讨论： + +- [GitHub Discussions](https://github.com/vercel/next.js/discussions) +- [Discord](https://discord.com/invite/bUG2bvbtHy) +- [Reddit](https://www.reddit.com/r/nextjs) + +## 社交媒体 + +关注 [Twitter](https://twitter.com/nextjs) 获取最新动态，订阅 [Vercel YouTube 频道](https://www.youtube.com/@VercelHQ) 观看 Next.js 相关视频。 + +## 行为准则 + +我们致力于创建包容、友好的社区环境。因此，我们要求所有成员遵守[行为准则](https://github.com/vercel/next.js/blob/canary/CODE_OF_CONDUCT.md)。该文件概述了我们对参与者行为的期望，请阅读并协助我们维护安全、尊重的社区环境。 \ No newline at end of file