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

next.config.js 配置选项

Next.js 可以通过项目根目录下的 next.config.js 文件（通常与 package.json 同级）进行配置，该文件需要导出一个默认配置对象。

next.config.js
// @ts-check

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

module.exports = nextConfig

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

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

next.config.mjs
// @ts-check

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

export default nextConfig

您也可以使用函数形式：

next.config.mjs
// @ts-check

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

自 Next.js 12.1.0 起，支持异步函数：

next.config.js
// @ts-check

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

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

// @ts-check

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 压缩功能用于压缩渲染内容和静态文件，该功能仅在使用服务器目标时生效。了解更多相关信息。

crossOrigin

使用 `crossOrigin` 选项为 `next/script` 生成的 `script` 标签添加跨域标签。

devIndicators

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

distDir

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

环境变量 (env)

了解如何在构建时向 Next.js 应用添加并访问环境变量。

eslint

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

exportPathMap

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

generateBuildId

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

generateEtags

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

headers

为您的 Next.js 应用添加自定义 HTTP 头部。

httpAgentOptions

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

图片

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

cacheHandler

配置 Next.js 用于存储和重新验证数据的缓存，以使用任何外部服务如 Redis、Memcached 或其他服务。

instrumentationHook

使用 instrumentationHook 选项在您的 Next.js 应用中设置 instrumentation。

日志记录

配置在开发模式下运行 Next.js 时如何将数据获取日志输出到控制台。

mdxRs

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

onDemandEntries

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

optimizePackageImports

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

output

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

pageExtensions

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

部分预渲染 (实验性功能)

了解如何在 Next.js 14 中启用部分预渲染 (实验性功能)。

poweredByHeader

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

productionBrowserSourceMaps

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

reactStrictMode

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

重定向

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

rewrites

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

serverActions

配置 Next.js 应用中的服务端操作 (Server Actions) 行为。

serverComponentsExternalPackages

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

StaleTimes (实验性功能)

了解如何覆盖客户端路由缓存 (Client Router Cache) 的失效时间。

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 问题的根源。

userAgent

userAgent 辅助工具扩展了 Web Request API，提供额外的属性和方法来与请求中的用户代理对象交互。

appDir

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