logoNext.js 简体中文
文档博客学习
简介/API 参考文档/next.config.js 配置选项

next.config.js 配置选项

Next.js 可以通过项目根目录下的 next.config.js 文件进行配置（例如，与 package.json 同级）。

next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  /* 在此处填写配置选项 */
}

module.exports = nextConfig

next.config.js 是一个常规的 Node.js 模块，而非 JSON 文件。它会被 Next.js 服务器和构建阶段使用，但不会包含在浏览器端的构建中。

如果需要使用 ECMAScript 模块，可以使用 next.config.mjs：

next.config.mjs
/**
 * @type {import('next').NextConfig}
 */
const nextConfig = {
  /* 在此处填写配置选项 */
}

export default nextConfig

您也可以使用函数形式：

next.config.mjs
module.exports = (phase, { defaultConfig }) => {
  /**
   * @type {import('next').NextConfig}
   */
  const nextConfig = {
    /* 在此处填写配置选项 */
  }
  return nextConfig
}

自 Next.js 12.1.0 起，您可以使用异步函数：

next.config.js
module.exports = async (phase, { defaultConfig }) => {
  /**
   * @type {import('next').NextConfig}
   */
  const nextConfig = {
    /* 在此处填写配置选项 */
  }
  return nextConfig
}

phase 表示加载配置时的当前上下文。您可以查看 可用阶段列表。这些阶段可以从 next/constants 导入：

const { PHASE_DEVELOPMENT_SERVER } = require('next/constants')

module.exports = (phase, { defaultConfig }) => {
  if (phase === PHASE_DEVELOPMENT_SERVER) {
    return {
      /* 仅开发环境使用的配置选项 */
    }
  }

  return {
    /* 除开发环境外所有阶段使用的配置选项 */
  }
}

注释行是您可以放置 next.config.js 允许的配置项的位置，这些配置项 在此文件中定义。

不过，所有配置都不是必需的，您也无需立即理解每个配置的作用。只需在本节中搜索您需要启用或修改的功能，文档会告诉您如何操作。

请避免使用目标 Node.js 版本不支持的 JavaScript 新特性。next.config.js 不会被 Webpack、Babel 或 TypeScript 解析。

本页记录了所有可用的配置选项：

appDir

启用应用路由 (App Router) 以使用布局 (layouts)、流式传输 (streaming) 等功能。

assetPrefix

了解如何使用 assetPrefix 配置选项来配置您的 CDN。

basePath

使用 `basePath` 将 Next.js 应用部署在域名的子路径下。

compress

Next.js 提供 gzip 压缩功能用于压缩渲染内容和静态文件，该功能仅适用于服务器目标。了解更多相关信息。

devIndicators

经过优化的页面会包含一个指示器，用于告知该页面是否正在进行静态优化。您可以在此选择禁用该功能。

distDir

设置自定义构建目录以替代默认的 .next 目录。

环境变量 (env)

学习如何在构建时向 Next.js 应用程序添加并访问环境变量。

eslint

Next.js 默认在构建过程中会报告 ESLint 错误和警告。本文介绍如何禁用此行为。

exportPathMap

自定义在使用 `next export` 时会被导出为 HTML 文件的页面。

generateBuildId

配置构建 ID，该 ID 用于标识当前提供服务的应用程序构建版本。

generateEtags

Next.js 默认会为每个页面生成 etag。了解如何在此处禁用 etag 生成。

headers

为你的 Next.js 应用添加自定义 HTTP 标头。

httpAgentOptions

Next.js 默认会自动使用 HTTP Keep-Alive。了解更多关于如何禁用 HTTP Keep-Alive 的信息。

图片配置

关于 next/image 加载器的自定义配置

incrementalCacheHandlerPath

配置用于存储和重新验证数据的 Next.js 缓存。

mdxRs

在 App Router 中使用新的 Rust 编译器来编译 MDX 文件。

onDemandEntries

配置 Next.js 在开发环境下如何处理内存中的页面创建与释放。

optimizePackageImports

关于 Next.js 配置选项 `optimizePackageImports` 的 API 参考文档

output

Next.js 会自动追踪每个页面所需的文件，以便轻松部署应用。了解其工作原理。

pageExtensions

扩展 Next.js 在解析 Pages Router 页面时使用的默认页面扩展名。

poweredByHeader

Next.js 默认会添加 `x-powered-by` 响应头。本文介绍如何禁用该功能。

productionBrowserSourceMaps

在生产环境构建期间启用浏览器源码映射 (source map) 生成功能。

reactStrictMode

完整的 Next.js 运行时现已兼容严格模式 (Strict Mode)，了解如何启用该功能

重定向

为您的 Next.js 应用添加重定向功能。

rewrites

为您的 Next.js 应用添加重写规则。

serverComponentsExternalPackages

将特定依赖项从服务端组件 (Server Components) 打包中排除，并使用原生 Node.js `require`。

trailingSlash

配置 Next.js 页面解析时是否包含尾部斜杠。

transpilePackages

自动转译并打包来自本地包（如 monorepos）或外部依赖（`node_modules`）的依赖项。

turbo

配置 Next.js 中特定于 Turbopack 的选项

typedRoutes

启用对静态类型链接的实验性支持。

TypeScript

Next.js 默认会报告 TypeScript 错误。本文介绍如何禁用此行为。

urlImports

配置 Next.js 以允许从外部 URL 导入模块（实验性功能）。

webpack

了解如何自定义 Next.js 使用的 webpack 配置

webVitalsAttribution

了解如何使用 webVitalsAttribution 选项来定位 Web Vitals 问题的根源。

useSelectedLayoutSegments

关于 `useSelectedLayoutSegments` 钩子的 API 参考文档。

appDir

启用应用路由 (App Router) 以使用布局 (layouts)、流式传输 (streaming) 等功能。