next.config.js

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

¥Next.js can be configured through a next.config.js file in the root of your project directory (for example, by package.json) with a default export.

// @ts-check

/** @type {import('next').NextConfig} */
const nextConfig = {
  /* config options here */
}

module.exports = nextConfig

ECMAScript 模块

¥ECMAScript Modules

next.config.js 是常规 Node.js 模块，而不是 JSON 文件。它由 Next.js 服务器和构建阶段使用，并且不包含在浏览器构建中。

¥next.config.js is a regular Node.js module, not a JSON file. It gets used by the Next.js server and build phases, and it's not included in the browser build.

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

¥If you need ECMAScript modules, you can use next.config.mjs:

// @ts-check

/**

 * @type {import('next').NextConfig}
 */
const nextConfig = {
  /* config options here */
}

export default nextConfig

很高兴知道：目前不支持带有 .cjs、.cts 或 .mts 扩展名的 next.config。

¥Good to know: next.config with the .cjs, .cts, or .mts extensions are currently not supported.

配置为函数

¥Configuration as a Function

你还可以使用一个函数：

¥You can also use a function:

// @ts-check

export default (phase, { defaultConfig }) => {
  /**

   * @type {import('next').NextConfig}
   */
  const nextConfig = {
    /* config options here */
  }
  return nextConfig
}

异步配置

¥Async Configuration

从 Next.js 12.1.0 开始，你可以使用异步函数：

¥Since Next.js 12.1.0, you can use an async function:

// @ts-check

module.exports = async (phase, { defaultConfig }) => {
  /**

   * @type {import('next').NextConfig}
   */
  const nextConfig = {
    /* config options here */
  }
  return nextConfig
}

阶段

¥Phase

phase 是加载配置的当前上下文。你可以看到 可用阶段。可以从 next/constants 导入相：

¥phase is the current context in which the configuration is loaded. You can see the available phases. Phases can be imported from next/constants:

// @ts-check

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

module.exports = (phase, { defaultConfig }) => {
  if (phase === PHASE_DEVELOPMENT_SERVER) {
    return {
      /* development only config options here */
    }
  }

  return {
    /* config options for all phases except development here */
  }
}

TypeScript

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

¥If you are using TypeScript in your project, you can use next.config.ts to use TypeScript in your configuration:

import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  /* config options here */
}

export default nextConfig

注释行是可以放置 next.config.js 允许的配置的地方，即 该文件中定义的。

¥The commented lines are the place where you can put the configs allowed by next.config.js, which are defined in this file.

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

¥However, none of the configs are required, and it's not necessary to understand what each config does. Instead, search for the features you need to enable or modify in this section and they will show you what to do.

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

¥Avoid using new JavaScript features not available in your target Node.js version. next.config.js will not be parsed by Webpack or Babel.

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

¥This page documents all the available configuration options:

单元测试（实验性）

¥Unit Testing (experimental)

从 Next.js 15.1 开始，next/experimental/testing/server 包包含帮助单元测试 next.config.js 文件的实用程序。

¥Starting in Next.js 15.1, the next/experimental/testing/server package contains utilities to help unit test next.config.js files.

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

¥The unstable_getResponseFromNextConfig function runs the headers, redirects, and rewrites functions from next.config.js with the provided request information and returns NextResponse with the results of the routing.

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

¥The response from unstable_getResponseFromNextConfig only considers next.config.js fields and does not consider middleware or filesystem routes, so the result in production may be different than the unit test.

import {
  getRedirectUrl,
  unstable_getResponseFromNextConfig,
} from 'next/experimental/testing/server'

const response = await unstable_getResponseFromNextConfig({
  url: 'https://next.nodejs.cn/test',
  nextConfig: {
    async redirects() {
      return [{ source: '/test', destination: '/test2', permanent: false }]
    },
  },
})
expect(response.status).toEqual(307)
expect(getRedirectUrl(response)).toEqual('https://next.nodejs.cn/test2')