From 72864e0259cc38ce1d71f3bd257f50f47b0e9796 Mon Sep 17 00:00:00 2001 From: xiaoyu2er Date: Thu, 5 Jun 2025 23:43:12 +0000 Subject: [PATCH] docs: update documentation translations --- .../02-project-structure.mdx | 2 - .../01-getting-started/10-updating-data.mdx | 44 ++-- .../docs/01-app/02-guides/memory-usage.mdx | 114 ++++++---- .../04-functions/generate-metadata.mdx | 206 +++++++++--------- .../05-config/01-next-config-js/turbopack.mdx | 73 ++++--- 5 files changed, 246 insertions(+), 193 deletions(-) diff --git a/apps/docs/content/zh-hans/docs/01-app/01-getting-started/02-project-structure.mdx b/apps/docs/content/zh-hans/docs/01-app/01-getting-started/02-project-structure.mdx index 29392379..8bd4e969 100644 --- a/apps/docs/content/zh-hans/docs/01-app/01-getting-started/02-project-structure.mdx +++ b/apps/docs/content/zh-hans/docs/01-app/01-getting-started/02-project-structure.mdx @@ -203,8 +203,6 @@ Next.js 对项目文件组织方式**不做强制要求**，但提供了多种 height="863" /> - - ### 文件同置 (Colocation) 在 `app` 目录中，嵌套文件夹定义了路由结构。每个文件夹代表一个路由片段，对应 URL 路径中的相应片段。 diff --git a/apps/docs/content/zh-hans/docs/01-app/01-getting-started/10-updating-data.mdx b/apps/docs/content/zh-hans/docs/01-app/01-getting-started/10-updating-data.mdx index ae41d722..675af726 100644 --- a/apps/docs/content/zh-hans/docs/01-app/01-getting-started/10-updating-data.mdx +++ b/apps/docs/content/zh-hans/docs/01-app/01-getting-started/10-updating-data.mdx @@ -1,9 +1,9 @@ --- -source-updated-at: 2025-06-01T01:32:19.000Z -translation-updated-at: 2025-06-01T01:32:19.000Z +source-updated-at: 2025-06-03T15:30:49.000Z +translation-updated-at: 2025-06-05T23:37:56.407Z title: 如何更新数据 -nav_title: 更新数据 -description: 了解如何在 Next.js 应用中更新数据。 +nav_title: 数据更新 +description: 学习如何在 Next.js 应用中更新数据。 related: title: API 参考 description: 通过阅读 API 参考文档了解更多本页提到的功能特性。 @@ -13,13 +13,13 @@ related: - app/api-reference/functions/redirect --- -你可以使用 React 的 [Server Functions](https://react.dev/reference/rsc/server-functions) 在 Next.js 中更新数据。本页将介绍如何[创建](#creating-server-functions)和[调用](#invoking-server-functions)服务端函数。 +您可以使用 React 的 [服务端函数 (Server Functions)](https://react.dev/reference/rsc/server-functions) 在 Next.js 中更新数据。本页将介绍如何[创建](#creating-server-functions)和[调用](#invoking-server-functions)服务端函数。 ## 服务端函数 -服务端函数是在服务器端执行的异步函数。由于它们是通过客户端网络请求调用的，因此本质上是异步的。当作为 `action` 的一部分被调用时，它们也被称为**服务端操作 (Server Actions)**。 +服务端函数是在服务器端执行的异步函数。由于它们是通过客户端发起的网络请求调用的，因此本质上是异步的。当作为 `action` 的一部分被调用时，它们也被称为**服务端操作 (Server Actions)**。 -按照约定，`action` 是传递给 `startTransition` 的异步函数。在以下情况下，服务端函数会自动被 `startTransition` 包裹： +按照约定，`action` 是传递给 `startTransition` 的异步函数。服务端函数在以下情况下会自动被 `startTransition` 包裹： - 通过 `action` 属性传递给 `
` - 通过 `formAction` 属性传递给 ` ) @@ -279,7 +279,7 @@ export function Button() { ```jsx filename="app/ui/button.js" switcher 'use client' -import { useActionState } from 'react' +import { useActionState, startTransition } from 'react' import { createPost } from '@/app/actions' import { LoadingSpinner } from '@/app/ui/loading-spinner' @@ -287,7 +287,7 @@ export function Button() { const [state, action, pending] = useActionState(createPost, false) return ( - ) @@ -296,7 +296,7 @@ export function Button() { ### 重新验证缓存 -执行更新后，可以通过在服务端函数中调用 [`revalidatePath`](/docs/app/api-reference/functions/revalidatePath) 或 [`revalidateTag`](/docs/app/api-reference/functions/revalidateTag) 来重新验证 Next.js 缓存并显示更新后的数据： +执行更新后，您可以通过在服务端函数中调用 [`revalidatePath`](/docs/app/api-reference/functions/revalidatePath) 或 [`revalidateTag`](/docs/app/api-reference/functions/revalidateTag) 来重新验证 Next.js 缓存并显示更新后的数据： ```ts filename="app/lib/actions.ts" switcher import { revalidatePath } from 'next/cache' @@ -323,7 +323,7 @@ export async function createPost(formData) { ### 重定向 -你可能希望在执行更新后将用户重定向到其他页面。可以通过在服务端函数中调用 [`redirect`](/docs/app/api-reference/functions/redirect) 实现： +您可能希望在执行更新后将用户重定向到其他页面。可以通过在服务端函数中调用 [`redirect`](/docs/app/api-reference/functions/redirect) 来实现： ```ts filename="app/lib/actions.ts" switcher 'use server' diff --git a/apps/docs/content/zh-hans/docs/01-app/02-guides/memory-usage.mdx b/apps/docs/content/zh-hans/docs/01-app/02-guides/memory-usage.mdx index 877b6f42..b86eda6c 100644 --- a/apps/docs/content/zh-hans/docs/01-app/02-guides/memory-usage.mdx +++ b/apps/docs/content/zh-hans/docs/01-app/02-guides/memory-usage.mdx @@ -1,76 +1,76 @@ --- -source-updated-at: 2025-05-16T04:52:11.000Z -translation-updated-at: 2025-05-19T23:03:16.407Z +source-updated-at: 2025-06-05T15:29:30.000Z +translation-updated-at: 2025-06-05T23:37:28.859Z title: 如何优化内存使用 -nav_title: 内存优化 -description: 优化开发与生产环境中应用程序的内存占用。 +nav_title: 内存使用 +description: 优化开发和生产环境中应用程序的内存占用。 --- -随着应用功能日益丰富，在本地开发或构建生产版本时可能会消耗更多资源。 +随着应用程序功能日益丰富，在本地开发或构建生产环境时可能会消耗更多资源。 -下面我们将探讨 Next.js 中优化内存和解决常见内存问题的策略与技巧。 +下面我们将探讨优化内存和解决 Next.js 中常见内存问题的策略与技巧。 ## 减少依赖项数量 -依赖项较多的应用会占用更多内存。 +依赖项较多的应用程序会占用更多内存。 -通过 [打包分析工具 (Bundle Analyzer)](/docs/app/guides/package-bundling) 可以检查应用中是否存在可移除的大型依赖项，从而提升性能和内存使用效率。 +使用[打包分析器](/docs/app/guides/package-bundling)可以帮助检查应用程序中的大型依赖项，移除不必要的依赖可以提升性能和减少内存占用。 ## 尝试 `experimental.webpackMemoryOptimizations` -从 `v15.0.0` 开始，您可以在 `next.config.js` 文件中添加 `experimental.webpackMemoryOptimizations: true` 来调整 Webpack 行为，这将降低最大内存占用，但可能会轻微增加编译时间。 +从 `v15.0.0` 开始，您可以在 `next.config.js` 中添加 `experimental.webpackMemoryOptimizations: true` 来调整 Webpack 行为，这将降低最大内存使用量，但可能会轻微增加编译时间。 -> **须知**：该功能目前处于实验阶段以收集更多项目测试数据，但被认为风险较低。 +> **须知**：该功能目前处于实验阶段，需要在更多项目中测试，但被认为风险较低。 ## 使用 `--experimental-debug-memory-usage` 运行 `next build` -从 `14.2.0` 开始，您可以运行 `next build --experimental-debug-memory-usage` 进入调试模式，Next.js 将在构建过程中持续输出内存使用信息（如堆内存使用情况和垃圾回收统计）。当内存使用接近配置上限时还会自动生成堆快照。 +从 `14.2.0` 开始，您可以运行 `next build --experimental-debug-memory-usage`，在此模式下 Next.js 会在构建过程中持续输出内存使用信息，包括堆内存使用情况和垃圾回收统计。当内存使用接近配置限制时，还会自动生成堆快照。 -> **须知**：此功能与 Webpack 构建工作线程选项不兼容（除非您使用自定义 webpack 配置，否则该选项默认启用）。 +> **须知**：此功能与 Webpack 构建工作线程选项不兼容，除非您有自定义 webpack 配置，否则该选项会自动启用。 -## 记录堆内存分析 +## 记录堆内存分析文件 -为排查内存问题，您可以记录 Node.js 的堆内存分析文件，并在 Chrome DevTools 中加载以识别潜在内存泄漏源。 +为了排查内存问题，您可以记录 Node.js 的堆内存分析文件，并在 Chrome DevTools 中加载以识别潜在的内存泄漏源。 -在终端中启动 Next.js 构建时添加 `--heap-prof` 参数： +在终端中启动 Next.js 构建时，向 Node.js 传递 `--heap-prof` 标志： ```sh node --heap-prof node_modules/next/dist/bin/next build ``` -构建结束后，Node.js 会生成 `.heapprofile` 文件。 +构建结束后，Node.js 会生成一个 `.heapprofile` 文件。 -在 Chrome DevTools 的 Memory 标签页中点击 "Load Profile" 按钮即可可视化分析该文件。 +在 Chrome DevTools 的 Memory 标签页中，点击 "Load Profile" 按钮即可可视化分析该文件。 ## 分析堆内存快照 -您可以使用调试工具分析应用的内存使用情况。 +您可以使用检查工具来分析应用程序的内存使用情况。 -运行 `next build` 或 `next dev` 命令时，在命令前添加 `NODE_OPTIONS=--inspect` 参数。这将在默认端口启动调试代理。若需在用户代码执行前中断，可使用 `--inspect-brk` 替代。当进程运行时，可通过 Chrome DevTools 等工具连接调试端口，记录并分析堆内存快照以查看内存占用情况。 +运行 `next build` 或 `next dev` 命令时，在命令开头添加 `NODE_OPTIONS=--inspect`。这将在默认端口上暴露检查器代理。如果希望在用户代码执行前中断，可以改用 `--inspect-brk`。当进程运行时，您可以使用 Chrome DevTools 等工具连接到调试端口，记录并分析堆内存快照以查看内存占用情况。 -从 `14.2.0` 开始，您也可以使用 `--experimental-debug-memory-usage` 标志运行 `next build` 来简化堆快照获取流程。 +从 `14.2.0` 开始，您还可以使用 `--experimental-debug-memory-usage` 标志运行 `next build`，这会使获取堆快照更加容易。 -在此模式下运行时，您可以随时向进程发送 `SIGUSR2` 信号，进程将立即生成堆快照。 +在此模式下运行时，您可以随时向进程发送 `SIGUSR2` 信号，进程将生成堆快照。 -快照会保存在 Next.js 应用的项目根目录，可用 Chrome DevTools 等堆内存分析工具加载查看内存保留情况。此模式目前暂不支持 Webpack 构建工作线程。 +堆快照将保存在 Next.js 应用程序的项目根目录中，可以在任何堆分析器（如 Chrome DevTools）中加载以查看内存保留情况。此模式目前尚不兼容 Webpack 构建工作线程。 -更多信息请参阅 [如何记录和分析堆快照](https://developer.chrome.com/docs/devtools/memory-problems/heap-snapshots)。 +有关详细信息，请参阅[如何记录和分析堆快照](https://developer.chrome.com/docs/devtools/memory-problems/heap-snapshots)。 ## Webpack 构建工作线程 -Webpack 构建工作线程允许在独立的 Node.js 工作线程中运行 Webpack 编译，从而降低构建时的内存占用。 +Webpack 构建工作线程允许在单独的 Node.js 工作线程中运行 Webpack 编译，这将减少构建期间的应用程序内存占用。 -从 `v14.1.0` 开始，若应用未使用自定义 Webpack 配置，该选项默认启用。 +从 `v14.1.0` 开始，如果应用程序没有自定义 Webpack 配置，此选项将默认启用。 -如果您使用旧版 Next.js 或有自定义 Webpack 配置，可通过在 `next.config.js` 中设置 `experimental.webpackBuildWorker: true` 启用此功能。 +如果您使用的是旧版 Next.js 或有自定义 Webpack 配置，可以通过在 `next.config.js` 中设置 `experimental.webpackBuildWorker: true` 来启用此选项。 -> **须知**：该功能可能与部分自定义 Webpack 插件不兼容。 +> **须知**：此功能可能与某些自定义 Webpack 插件不兼容。 ## 禁用 Webpack 缓存 -[Webpack 缓存](https://webpack.js.org/configuration/cache/) 会将生成的 Webpack 模块保存在内存或磁盘中以加速构建。虽然能提升性能，但存储缓存数据也会增加应用内存占用。 +[Webpack 缓存](https://webpack.js.org/configuration/cache/)将生成的 Webpack 模块保存在内存和/或磁盘上以提高构建速度。这有助于提升性能，但也会增加应用程序的内存占用以存储缓存数据。 -您可以通过添加 [自定义 Webpack 配置](/docs/app/api-reference/config/next-config-js/webpack) 来禁用此行为： +您可以通过为应用程序添加[自定义 Webpack 配置](/docs/app/api-reference/config/next-config-js/webpack)来禁用此行为： ```js filename="next.config.mjs" /** @type {import('next').NextConfig} */ @@ -84,7 +84,7 @@ const nextConfig = { type: 'memory', }) } - // 重要：必须返回修改后的配置 + // 重要：返回修改后的配置 return config }, } @@ -94,18 +94,20 @@ export default nextConfig ## 禁用静态分析 -类型检查和代码检查可能在大型项目中消耗大量内存。但大多数项目已有专门的 CI 流程处理这些任务。当构建在 "Linting and checking validity of types" 步骤出现内存不足问题时，可以在构建时禁用这些任务： +类型检查和代码检查可能会消耗大量内存，特别是在大型项目中。 +然而，大多数项目都有专门的 CI 运行器来处理这些任务。 +当构建在 "Linting and checking validity of types" 步骤中出现内存不足问题时，您可以在构建期间禁用这些任务： ```js filename="next.config.mjs" /** @type {import('next').NextConfig} */ const nextConfig = { eslint: { - // 警告：即使项目存在 ESLint 错误，也允许构建完成 + // 警告：即使项目存在 ESLint 错误，此设置也允许生产构建成功完成 ignoreDuringBuilds: true, }, typescript: { // !! 警告 !! - // 即使项目存在类型错误，也允许构建完成 + // 即使项目存在类型错误，也允许生产构建成功完成 // !! 警告 !! ignoreBuildErrors: true, }, @@ -117,16 +119,50 @@ export default nextConfig - [忽略 TypeScript 错误](/docs/app/api-reference/config/typescript#disabling-typescript-errors-in-production) - [Next.js 配置中的 ESLint](/docs/pages/api-reference/config/next-config-js/eslint) -请注意这可能导致因类型错误或代码问题产生有缺陷的部署。我们强烈建议仅在静态分析完成后才将构建推送到生产环境。如果您部署到 Vercel，可参阅 [预发布部署指南](https://vercel.com/docs/deployments/managing-deployments#staging-and-promoting-a-production-deployment) 了解如何在自定义任务成功后发布生产构建。 +请注意，这可能会因类型错误或代码检查问题导致部署失败。 +我们强烈建议仅在静态分析完成后才将构建推送到生产环境。如果您部署到 Vercel，可以查看[暂存部署指南](https://vercel.com/docs/deployments/managing-deployments#staging-and-promoting-a-production-deployment)了解如何在自定义任务成功后提升构建至生产环境。 -## 禁用 Source Maps +## 禁用源映射 -生成 source maps 会额外消耗构建过程的内存。 +生成源映射会在构建过程中消耗额外内存。 -您可以通过在 Next.js 配置中添加 `productionBrowserSourceMaps: false` 和 `experimental.serverSourceMaps: false` 来禁用 source map 生成。 +您可以通过在 Next.js 配置中添加 `productionBrowserSourceMaps: false` 和 `experimental.serverSourceMaps: false` 来禁用源映射生成。 -> **须知**：某些插件可能会启用 source maps，可能需要额外配置才能禁用。 +> **须知**：某些插件可能会启用源映射，可能需要自定义配置才能禁用。 ## Edge 运行时内存问题 -Next.js `v14.1.3` 修复了使用 Edge 运行时时的内存问题。请升级至该版本（或更高版本）以确认是否解决您的问题。 \ No newline at end of file +Next.js `v14.1.3` 修复了使用 Edge 运行时的内存问题。请升级到此版本（或更高版本）以确认是否解决了您的问题。 + +## 预加载入口 + +当 Next.js 服务器启动时，它会将每个页面的 JavaScript 模块预加载到内存中，而不是在请求时加载。 + +这种优化以更大的初始内存占用为代价，换取更快的响应时间。 + +要禁用此优化，请将 `experimental.preloadEntriesOnStart` 标志设置为 `false`。 + +```ts filename="next.config.ts" switcher +import type { NextConfig } from 'next' + +const config: NextConfig = { + experimental: { + preloadEntriesOnStart: false, + }, +} + +export default config +``` + +```js filename="next.config.mjs" switcher +/** @type {import('next').NextConfig} */ +const config = { + experimental: { + preloadEntriesOnStart: false, + }, +} + +export default config +``` + +Next.js 不会卸载这些 JavaScript 模块，这意味着即使禁用此优化，如果最终请求了所有页面，Next.js 服务器的内存占用最终也会相同。 \ No newline at end of file diff --git a/apps/docs/content/zh-hans/docs/01-app/05-api-reference/04-functions/generate-metadata.mdx b/apps/docs/content/zh-hans/docs/01-app/05-api-reference/04-functions/generate-metadata.mdx index 91284657..ede067c4 100644 --- a/apps/docs/content/zh-hans/docs/01-app/05-api-reference/04-functions/generate-metadata.mdx +++ b/apps/docs/content/zh-hans/docs/01-app/05-api-reference/04-functions/generate-metadata.mdx @@ -1,10 +1,10 @@ --- -source-updated-at: 2025-06-01T01:32:20.000Z -translation-updated-at: 2025-06-01T22:19:03.803Z +source-updated-at: 2025-06-05T15:29:30.000Z +translation-updated-at: 2025-06-05T23:43:11.978Z title: generateMetadata -description: 了解如何为 Next.js 应用添加元数据以提升搜索引擎优化 (SEO) 和网页分享能力。 +description: 了解如何为 Next.js 应用添加元数据 (Metadata) 以提升搜索引擎优化 (SEO) 和网页分享能力。 related: - title: 下一步 + title: 后续步骤 description: 查看所有元数据 API 选项。 links: - app/api-reference/file-conventions/metadata @@ -37,11 +37,11 @@ export const metadata = { export default function Page() {} ``` -> 查看 [元数据字段](#metadata-fields) 获取完整的支持选项列表。 +> 完整支持的选项列表请参阅 [元数据字段](#metadata-fields)。 ## `generateMetadata` 函数 -动态元数据依赖于**动态信息**，例如当前路由参数、外部数据或父段中的 `metadata`，可以通过导出一个返回 [`Metadata` 对象](#metadata-fields) 的 `generateMetadata` 函数来设置。 +依赖于**动态信息**的元数据，例如当前路由参数、外部数据或父级段中的 `metadata`，可以通过导出一个返回 [`Metadata` 对象](#metadata-fields) 的 `generateMetadata` 函数来设置。 ```tsx filename="app/products/[id]/page.tsx" switcher import type { Metadata, ResolvingMetadata } from 'next' @@ -61,7 +61,7 @@ export async function generateMetadata( // 获取数据 const product = await fetch(`https://.../${id}`).then((res) => res.json()) - // 可选地访问并扩展（而非替换）父元数据 + // 可选：访问并扩展（而非替换）父级元数据 const previousImages = (await parent).openGraph?.images || [] return { @@ -83,7 +83,7 @@ export async function generateMetadata({ params, searchParams }, parent) { // 获取数据 const product = await fetch(`https://.../${id}`).then((res) => res.json()) - // 可选地访问并扩展（而非替换）父元数据 + // 可选：访问并扩展（而非替换）父级元数据 const previousImages = (await parent).openGraph?.images || [] return { @@ -101,11 +101,11 @@ export default function Page({ params, searchParams }) {} > > - 元数据可以添加到 `layout.js` 和 `page.js` 文件中。 > - Next.js 会自动解析元数据，并为页面创建相关的 `` 标签。 -> - `metadata` 对象和 `generateMetadata` 函数导出**仅在服务端组件中支持**。 -> - 不能从同一路由段同时导出 `metadata` 对象和 `generateMetadata` 函数。 -> - `generateMetadata` 中的 `fetch` 请求会自动[记忆化](/docs/app/deep-dive/caching#request-memoization)，以便在 `generateMetadata`、`generateStaticParams`、布局、页面和服务端组件之间共享相同的数据。 -> - 如果 `fetch` 不可用，可以使用 React 的 [`cache` 函数](/docs/app/deep-dive/caching#react-cache-function)。 -> - [基于文件的元数据](/docs/app/api-reference/file-conventions/metadata)具有更高的优先级，会覆盖 `metadata` 对象和 `generateMetadata` 函数。 +> - `metadata` 对象和 `generateMetadata` 函数导出**仅支持在服务端组件 (Server Components)** 中使用。 +> - 不能从同一个路由段同时导出 `metadata` 对象和 `generateMetadata` 函数。 +> - `generateMetadata` 中的 `fetch` 请求会自动[记忆化](/docs/app/deep-dive/caching#request-memoization)，以便在 `generateMetadata`、`generateStaticParams`、布局 (Layouts)、页面 (Pages) 和服务端组件 (Server Components) 之间共享相同数据。 +> - 如果无法使用 `fetch`，可以使用 React 的 [`cache` 函数](/docs/app/deep-dive/caching#react-cache-function)。 +> - [基于文件的元数据](/docs/app/api-reference/file-conventions/metadata) 具有更高优先级，会覆盖 `metadata` 对象和 `generateMetadata` 函数。 ## 参考 @@ -114,32 +114,32 @@ export default function Page({ params, searchParams }) {} `generateMetadata` 函数接受以下参数： - `props` - 包含当前路由参数的对象： - - `params` - 包含从根段到调用 `generateMetadata` 的段的[动态路由参数](/docs/app/api-reference/file-conventions/dynamic-routes)对象。示例： + - `params` - 包含从根段到调用 `generateMetadata` 的段的[动态路由参数](/docs/app/api-reference/file-conventions/dynamic-routes) 对象。示例： - | 路由 | URL | `params` | - | ------------------------------- | ----------- | ------------------------- | - | `app/shop/[slug]/page.js` | `/shop/1` | `{ slug: '1' }` | - | `app/shop/[tag]/[item]/page.js` | `/shop/1/2` | `{ tag: '1', item: '2' }` | - | `app/shop/[...slug]/page.js` | `/shop/1/2` | `{ slug: ['1', '2'] }` | + | 路由 | URL | `params` | + | ------------------------------- | ------------ | -------------------------- | + | `app/shop/[slug]/page.js` | `/shop/1` | `{ slug: '1' }` | + | `app/shop/[tag]/[item]/page.js` | `/shop/1/2` | `{ tag: '1', item: '2' }` | + | `app/shop/[...slug]/page.js` | `/shop/1/2` | `{ slug: ['1', '2'] }` | - - `searchParams` - 包含当前 URL 的[查询参数](https://developer.mozilla.org/docs/Learn/Common_questions/What_is_a_URL#parameters)的对象。示例： + - `searchParams` - 包含当前 URL 的[查询参数](https://developer.mozilla.org/docs/Learn/Common_questions/What_is_a_URL#parameters) 的对象。示例： - | URL | `searchParams` | - | --------------- | -------------------- | - | `/shop?a=1` | `{ a: '1' }` | - | `/shop?a=1&b=2` | `{ a: '1', b: '2' }` | - | `/shop?a=1&a=2` | `{ a: ['1', '2'] }` | + | URL | `searchParams` | + | ---------------- | --------------------- | + | `/shop?a=1` | `{ a: '1' }` | + | `/shop?a=1&b=2` | `{ a: '1', b: '2' }` | + | `/shop?a=1&a=2` | `{ a: ['1', '2'] }` | -- `parent` - 父路由段解析后的元数据的 Promise。 +- `parent` - 父级路由段解析后的元数据的 Promise。 ### 返回值 -`generateMetadata` 应返回一个包含一个或多个元数据字段的 [`Metadata` 对象](#metadata-fields)。 +`generateMetadata` 应返回包含一个或多个元数据字段的 [`Metadata` 对象](#metadata-fields)。 > **须知**： > -> - 如果元数据不依赖于运行时信息，应使用静态的 [`metadata` 对象](#the-metadata-object)而非 `generateMetadata` 来定义。 -> - `fetch` 请求会自动[记忆化](/docs/app/deep-dive/caching#request-memoization)，以便在 `generateMetadata`、`generateStaticParams`、布局、页面和服务端组件之间共享相同的数据。如果 `fetch` 不可用，可以使用 React 的 [`cache` 函数](/docs/app/deep-dive/caching#react-cache-function)。 +> - 如果元数据不依赖于运行时信息，应使用静态 [`metadata` 对象](#the-metadata-object) 而非 `generateMetadata` 来定义。 +> - `fetch` 请求会自动[记忆化](/docs/app/deep-dive/caching#request-memoization)，以便在 `generateMetadata`、`generateStaticParams`、布局 (Layouts)、页面 (Pages) 和服务端组件 (Server Components) 之间共享相同数据。如果无法使用 `fetch`，可以使用 React 的 [`cache` 函数](/docs/app/deep-dive/caching#react-cache-function)。 > - `searchParams` 仅在 `page.js` 段中可用。 > - Next.js 的 [`redirect()`](/docs/app/api-reference/functions/redirect) 和 [`notFound()`](/docs/app/api-reference/functions/not-found) 方法也可以在 `generateMetadata` 中使用。 @@ -149,7 +149,7 @@ export default function Page({ params, searchParams }) {} #### `title` -`title` 属性用于设置文档的标题。可以定义为简单的[字符串](#string)或可选的[模板对象](#template)。 +`title` 属性用于设置文档标题。可以定义为简单的[字符串](#string) 或可选的[模板对象](#template)。 ##### 字符串 @@ -159,7 +159,7 @@ export const metadata = { } ``` -```html filename=" output" hideLineNumbers +```html filename=" 输出" hideLineNumbers Next.js ``` @@ -187,7 +187,7 @@ export const metadata: Metadata = {} ##### `template` -`title.template` 可用于为**子**路由段中定义的 `title` 添加前缀或后缀。 +`title.template` 可用于为**子**路由段中定义的 `titles` 添加前缀或后缀。 ```tsx filename="app/layout.tsx" switcher import type { Metadata } from 'next' @@ -230,16 +230,14 @@ export const metadata = { > **须知**： > > - `title.template` 应用于**子**路由段，而非定义它的段。这意味着： -> > - 添加 `title.template` 时，`title.default` 是**必需的**。 > - `layout.js` 中定义的 `title.template` 不会应用于同一路由段的 `page.js` 中定义的 `title`。 -> - `page.js` 中定义的 `title.template` 无效，因为页面始终是终止段（它没有任何子路由段）。 -> +> - `page.js` 中定义的 `title.template` 无效，因为页面始终是路由的终止段（它没有任何子路由段）。 > - 如果路由未定义 `title` 或 `title.default`，`title.template` **无效**。 ##### `absolute` -`title.absolute` 可用于提供**忽略**父段中设置的 `title.template` 的标题。 +`title.absolute` 可用于提供**忽略**父级段中设置的 `title.template` 的标题。 ```tsx filename="app/layout.tsx" switcher import type { Metadata } from 'next' @@ -284,27 +282,25 @@ export const metadata = { > **须知**： > > - `layout.js` -> -> - `title` (字符串) 和 `title.default` 为子段（未定义自己的 `title` 的段）定义默认标题。如果存在，它将扩展最近父段的 `title.template`。 -> - `title.absolute` 为子段定义默认标题。它忽略父段的 `title.template`。 +> - `title` (字符串) 和 `title.default` 为子段（未定义自己的 `title` 时）定义默认标题。如果存在最近的父级段的 `title.template`，它将增强该模板。 +> - `title.absolute` 为子段定义默认标题。它会忽略父级段的 `title.template`。 > - `title.template` 为子段定义新的标题模板。 -> > - `page.js` -> - 如果页面未定义自己的标题，将使用最近父段解析后的标题。 -> - `title` (字符串) 定义路由的标题。如果存在，它将扩展最近父段的 `title.template`。 -> - `title.absolute` 定义路由标题。它忽略父段的 `title.template`。 +> - 如果页面未定义自己的标题，将使用最近的父级解析后的标题。 +> - `title` (字符串) 定义路由标题。如果存在最近的父级段的 `title.template`，它将增强该模板。 +> - `title.absolute` 定义路由标题。它会忽略父级段的 `title.template`。 > - `title.template` 在 `page.js` 中无效，因为页面始终是路由的终止段。 ### `description` ```jsx filename="layout.js | page.js" export const metadata = { - description: 'The React Framework for the Web', + description: '面向 Web 的 React 框架', } ``` -```html filename=" output" hideLineNumbers - +```html filename=" 输出" hideLineNumbers + ``` ### 其他字段 @@ -326,7 +322,7 @@ export const metadata = { } ``` -```html filename=" output" hideLineNumbers +```html filename=" 输出" hideLineNumbers @@ -344,7 +340,7 @@ export const metadata = { `metadataBase` 是一个便捷选项，用于为需要完全限定 URL 的 `metadata` 字段设置基础 URL 前缀。 -- `metadataBase` 允许**当前路由段及以下**定义的基于 URL 的 `metadata` 字段使用**相对路径**，而非必需的绝对 URL。 +- `metadataBase` 允许**当前路由段及以下**的基于 URL 的 `metadata` 字段使用**相对路径**，而非必须的绝对 URL。 - 字段的相对路径将与 `metadataBase` 组合形成完全限定的 URL。 ```jsx filename="layout.js | page.js" @@ -363,7 +359,7 @@ export const metadata = { } ``` -```html filename=" output" hideLineNumbers +```html filename=" 输出" hideLineNumbers @@ -372,19 +368,19 @@ export const metadata = { > **须知**： > -> - `metadataBase` 通常设置在根 `app/layout.js` 中，以应用于所有路由中基于 URL 的 `metadata` 字段。 +> - `metadataBase` 通常设置在根 `app/layout.js` 中，以应用于所有路由的基于 URL 的 `metadata` 字段。 > - 所有需要绝对 URL 的基于 URL 的 `metadata` 字段都可以通过 `metadataBase` 选项进行配置。 > - `metadataBase` 可以包含子域名（例如 `https://app.acme.com`）或基础路径（例如 `https://acme.com/start/from/here`）。 -> - 如果 `metadata` 字段提供了绝对 URL，`metadataBase` 将被忽略。 -> - 在不配置 `metadataBase` 的情况下在基于 URL 的 `metadata` 字段中使用相对路径会导致构建错误。 -> - Next.js 会规范化 `metadataBase`（例如 `https://acme.com/`）和相对字段（例如 `/path`）之间的重复斜杠为单个斜杠（例如 `https://acme.com/path`）。 +> - 如果 `metadata` 字段提供绝对 URL，`metadataBase` 将被忽略。 +> - 在未配置 `metadataBase` 的情况下在基于 URL 的 `metadata` 字段中使用相对路径会导致构建错误。 +> - Next.js 会规范化 `metadataBase`（例如 `https://acme.com/`）和相对字段（例如 `/path`）之间的重复斜杠为单斜杠（例如 `https://acme.com/path`）。 #### URL 组合 URL 组合优先考虑开发者的意图而非默认的目录遍历语义。 - `metadataBase` 和 `metadata` 字段之间的尾部斜杠会被规范化。 -- `metadata` 字段中的“绝对”路径（通常替换整个 URL 路径）被视为“相对”路径（从 `metadataBase` 的末尾开始）。 +- `metadata` 字段中的"绝对"路径（通常替换整个 URL 路径）被视为"相对"路径（从 `metadataBase` 的末尾开始）。 例如，给定以下 `metadataBase`： @@ -402,9 +398,9 @@ export const metadata = { } ``` -继承上述 `metadataBase` 并设置自己值的任何 `metadata` 字段将按以下方式解析： +继承上述 `metadataBase` 并设置自身值的任何 `metadata` 字段将按以下方式解析： -| `metadata` 字段 | 解析后的 URL | +| `metadata` 字段 | 解析后的 URL | | -------------------------------- | -------------------------------- | | `/` | `https://acme.com` | | `./` | `https://acme.com` | @@ -420,7 +416,7 @@ export const metadata = { export const metadata = { openGraph: { title: 'Next.js', - description: 'The React Framework for the Web', + description: '面向 Web 的 React 框架', url: 'https://nextjs.org', siteName: 'Next.js', images: [ @@ -433,7 +429,7 @@ export const metadata = { url: 'https://nextjs.org/og-alt.png', // 必须是绝对 URL width: 1800, height: 1600, - alt: '我的自定义替代文本', + alt: '自定义替代文本', }, ], videos: [ @@ -456,7 +452,7 @@ export const metadata = { ```html filename=" output" hideLineNumbers - + @@ -466,7 +462,7 @@ export const metadata = { - + @@ -478,7 +474,7 @@ export const metadata = { export const metadata = { openGraph: { title: 'Next.js', - description: 'The React Framework for the Web', + description: '面向 Web 的 React 框架', type: 'article', publishedTime: '2023-01-01T00:00:00.000Z', authors: ['Seb', 'Josh'], @@ -488,7 +484,7 @@ export const metadata = { ```html filename=" output" hideLineNumbers - + @@ -497,7 +493,7 @@ export const metadata = { > **须知**: > -> - 对于 Open Graph 图片，使用 [基于文件的元数据 API](/docs/app/api-reference/file-conventions/metadata/opengraph-image#image-files-jpg-png-gif) 可能更方便。无需手动同步配置导出与实际文件，基于文件的 API 会自动为您生成正确的元数据。 +> - 对于 Open Graph 图片，使用[基于文件的元数据 API](/docs/app/api-reference/file-conventions/metadata/opengraph-image#image-files-jpg-png-gif)可能更方便。无需手动同步配置导出与实际文件，基于文件的 API 会自动生成正确的元数据。 ### `robots` @@ -531,7 +527,7 @@ export const metadata: Metadata = { ### `icons` -> **须知**：我们建议尽可能使用 [基于文件的元数据 API](/docs/app/api-reference/file-conventions/metadata/app-icons#image-files-ico-jpg-png) 来处理图标。无需手动同步配置导出与实际文件，基于文件的 API 会自动为您生成正确的元数据。 +> **须知**: 建议尽可能使用[基于文件的元数据 API](/docs/app/api-reference/file-conventions/metadata/app-icons#image-files-ico-jpg-png)来管理图标。无需手动同步配置导出与实际文件，基于文件的 API 会自动生成正确的元数据。 ```jsx filename="layout.js | page.js" export const metadata = { @@ -598,19 +594,19 @@ export const metadata = { /> ``` -> **须知**：`msapplication-*` 元标签在 Microsoft Edge 的 Chromium 版本中不再支持，因此不再需要。 +> **须知**: Chromium 构建的 Microsoft Edge 不再支持 `msapplication-*` 元标签，因此不再需要。 ### `themeColor` -> **已弃用**：从 Next.js 14 开始，`metadata` 中的 `themeColor` 选项已弃用。请改用 [`viewport` 配置](/docs/app/api-reference/functions/generate-viewport)。 +> **已弃用**: 从 Next.js 14 开始，`metadata` 中的 `themeColor` 选项已被弃用。请改用 [`viewport` 配置](/docs/app/api-reference/functions/generate-viewport)。 ### `colorScheme` -> **已弃用**：从 Next.js 14 开始，`metadata` 中的 `colorScheme` 选项已弃用。请改用 [`viewport` 配置](/docs/app/api-reference/functions/generate-viewport)。 +> **已弃用**: 从 Next.js 14 开始，`metadata` 中的 `colorScheme` 选项已被弃用。请改用 [`viewport` 配置](/docs/app/api-reference/functions/generate-viewport)。 ### `manifest` -Web 应用程序清单，定义在 [Web 应用程序清单规范](https://developer.mozilla.org/docs/Web/Manifest) 中。 +Web 应用清单，定义在 [Web 应用清单规范](https://developer.mozilla.org/docs/Web/Manifest)中。 ```jsx filename="layout.js | page.js" export const metadata = { @@ -633,7 +629,7 @@ export const metadata = { twitter: { card: 'summary_large_image', title: 'Next.js', - description: 'The React Framework for the Web', + description: '面向 Web 的 React 框架', siteId: '1467726470533754880', creator: '@nextjs', creatorId: '1467726470533754880', @@ -648,7 +644,7 @@ export const metadata = { - + ``` @@ -657,7 +653,7 @@ export const metadata = { twitter: { card: 'app', title: 'Next.js', - description: 'The React Framework for the Web', + description: '面向 Web 的 React 框架', siteId: '1467726470533754880', creator: '@nextjs', creatorId: '1467726470533754880', @@ -686,7 +682,7 @@ export const metadata = { - + @@ -702,7 +698,7 @@ export const metadata = { ### `viewport` -> **已弃用**：从 Next.js 14 开始，`metadata` 中的 `viewport` 选项已弃用。请改用 [`viewport` 配置](/docs/app/api-reference/functions/generate-viewport)。 +> **已弃用**: 从 Next.js 14 开始，`metadata` 中的 `viewport` 选项已被弃用。请改用 [`viewport` 配置](/docs/app/api-reference/functions/generate-viewport)。 ### `verification` @@ -889,9 +885,9 @@ export const metadata = { ### `facebook` -您可以将 Facebook 应用或 Facebook 账户连接到您的网页，以使用某些 Facebook 社交插件 [Facebook 文档](https://developers.facebook.com/docs/plugins/comments/#moderation-setup-instructions) +您可以将 Facebook 应用或 Facebook 帐户连接到网页，以使用某些 Facebook 社交插件 [Facebook 文档](https://developers.facebook.com/docs/plugins/comments/#moderation-setup-instructions) -> **须知**：您可以指定 appId 或 admins，但不能同时指定两者。 +> **须知**: 您可以指定 appId 或 admins，但不能同时指定两者。 ```jsx filename="layout.js | page.js" export const metadata = { @@ -984,7 +980,7 @@ export const metadata = { ### 类型 -您可以通过使用 `Metadata` 类型为元数据添加类型安全。如果您的 IDE 中使用了[内置的 TypeScript 插件](/docs/app/api-reference/config/typescript)，则无需手动添加类型，但仍可以显式添加。 +您可以通过使用 `Metadata` 类型为元数据添加类型安全。如果您的 IDE 中使用了[内置 TypeScript 插件](/docs/app/api-reference/config/typescript)，则无需手动添加类型，但仍可显式添加。 #### `metadata` 对象 @@ -1067,23 +1063,23 @@ export const metadata = { } ``` -| 元数据 | 推荐做法 | +| 元数据 | 推荐方案 | | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `` | 通过 [`redirect()`](/docs/app/api-reference/functions/redirect)、[中间件](/docs/app/building-your-application/routing/middleware#nextresponse) 或 [安全头](/docs/app/api-reference/config/next-config-js/headers) 使用适当的 HTTP 头 | -| `` | 在布局或页面中直接渲染该标签。 | -| `