Menu

next.config.js

Next.js 可以通过项目目录根目录中的 next.config.js 文件进行配置（例如，与 package.json 同级），并使用默认导出。

next.config.js
// @ts-check
 
/** @type {import('next').NextConfig} */
const nextConfig = {
  /* 在这里配置选项 */
}
 
module.exports = nextConfig

ECMAScript 模块

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

值得注意的是：目前不支持使用 .cjs、.cts 或 .mts 扩展名的 next.config 文件。

配置作为函数

你也可以使用函数：

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

phase 是加载配置时的当前上下文。你可以查看可用的 phases。Phases 可以从 next/constants 导入：

next.config.js
// @ts-check
 
const { PHASE_DEVELOPMENT_SERVER } = require('next/constants')
 
module.exports = (phase, { defaultConfig }) => {
  if (phase === PHASE_DEVELOPMENT_SERVER) {
    return {
      /* 仅开发环境的配置选项 */
    }
  }
 
  return {
    /* 除开发环境外所有阶段的配置选项 */
  }
}

TypeScript

如果你在项目中使用 TypeScript，可以使用 next.config.ts 在配置中使用 TypeScript：

next.config.ts
import type { NextConfig } from 'next'
 
const nextConfig: NextConfig = {
  /* 在这里配置选项 */
}
 
export default nextConfig

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

然而，所有配置都不是必需的，也没有必要理解每个配置的作用。相反，在本节中搜索你需要启用或修改的功能，它们会告诉你该怎么做。

避免使用目标 Node.js 版本中不可用的新 JavaScript 特性。next.config.js 不会被 Webpack 或 Babel 解析。

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

单元测试（实验性）

从 Next.js 15.1 开始，next/experimental/testing/server 包包含了帮助对 next.config.js 文件进行单元测试的实用工具。

unstable_getResponseFromNextConfig 函数使用提供的请求信息运行 next.config.js 中的 headers、redirects 和 rewrites 函数，并返回包含路由结果的 NextResponse。

来自 unstable_getResponseFromNextConfig 的响应仅考虑 next.config.js 字段，不考虑代理或文件系统路由，因此生产环境中的结果可能与单元测试不同。

import {
  getRedirectUrl,
  unstable_getResponseFromNextConfig,
} from 'next/experimental/testing/server'
 
const response = await unstable_getResponseFromNextConfig({
  url: 'https://nextjs.org/test',
  nextConfig: {
    async redirects() {
      return [{ source: '/test', destination: '/test2', permanent: false }]
    },
  },
})
expect(response.status).toEqual(307)
expect(getRedirectUrl(response)).toEqual('https://nextjs.org/test2')

experimental.adapterPath

配置一个自定义适配器，让 Next.js 通过 modifyConfig 和 onBuildComplete 回调钩入构建过程。

allowedDevOrigins

使用 `allowedDevOrigins` 配置可以请求开发服务器的其他源。

appDir

启用 App Router 以使用布局、流式传输等功能。

assetPrefix

学习如何使用 assetPrefix 配置选项来配置你的 CDN。

authInterrupts

了解如何启用实验性的 `authInterrupts` 配置选项以使用 `forbidden` 和 `unauthorized`。

basePath

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

browserDebugInfoInTerminal

在开发过程中将浏览器控制台日志和错误转发到你的终端。

cacheComponents

了解如何在 Next.js 中启用 cacheComponents 标志。

cacheLife

学习如何在 Next.js 中设置 cacheLife 配置。

compress

Next.js 提供 gzip 压缩来压缩渲染内容和静态文件，它只适用于服务器目标。在此处了解更多信息。

crossOrigin

使用 `crossOrigin` 选项在 `next/script` 生成的 `script` 标签上添加 crossOrigin 属性。

cssChunking

使用 `cssChunking` 选项来控制 Next.js 应用中 CSS 文件的分块方式。

devIndicators

配置选项，用于在开发过程中显示屏幕上的指示器，提供当前查看路由的上下文信息。

distDir

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

env

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

expireTime

为启用 ISR 的页面自定义 stale-while-revalidate 过期时间。

exportPathMap

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

generateBuildId

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

generateEtags

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

headers

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

htmlLimitedBots

指定应接收阻塞元数据的用户代理列表。

httpAgentOptions

Next.js 默认会自动使用 HTTP Keep-Alive。了解如何在此处禁用 HTTP Keep-Alive。

images

next/image loader 的自定义配置

cacheHandler

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

inlineCss

启用内联 CSS 支持。

isolatedDevBuild

为开发服务器使用隔离的构建输出，以防止与生产构建发生冲突。

logging

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

mdxRs

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

onDemandEntries

配置 Next.js 在开发环境中如何处理和保持页面在内存中。

optimizePackageImports

optimizePackageImports Next.js 配置选项的 API 参考

output

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

pageExtensions

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

poweredByHeader

Next.js 默认会添加 `x-powered-by` 头。在此了解如何选择退出。

productionBrowserSourceMaps

在生产构建期间启用浏览器源映射生成。

proxyClientMaxBodySize

配置使用 proxy 时的最大请求体大小。

reactCompiler

启用 React Compiler 以自动优化组件渲染。

reactMaxHeadersLength

React 发出并添加到响应中的 headers 的最大长度。

reactStrictMode

Next.js 运行时现已完全兼容严格模式，了解如何启用

redirects

为你的 Next.js 应用添加重定向。

rewrites

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

sassOptions

配置 Sass 选项。

serverActions

配置 Next.js 应用程序中的 Server Actions 行为。

serverComponentsHmrCache

配置在服务器组件中是否在 HMR 刷新请求之间缓存 fetch 响应。

serverExternalPackages

从 Server Components 打包中排除特定依赖项，并使用原生 Node.js `require`。

staleTimes

了解如何覆盖客户端路由缓存的失效时间。

staticGeneration*

了解如何在 Next.js 应用中配置静态生成。

taint

启用对象和值的污染标记功能。

trailingSlash

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

transpilePackages

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

turbopack

使用 Turbopack 特定选项配置 Next.js

turbopackFileSystemCache

了解如何为 Turbopack 构建启用文件系统缓存

typedRoutes

启用静态类型链接的支持。

typescript

Next.js 默认会报告 TypeScript 错误。在这里了解如何选择退出此行为。

urlImports

配置 Next.js 以允许从外部 URL 导入模块。

useLightningcss

启用对 Lightning CSS 的实验性支持。

viewTransition

在 App Router 中启用 React 的 ViewTransition API

webVitalsAttribution

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

webpack

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