next.config.js

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

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 是加载配置的当前上下文。你可以查看 可用阶段。阶段可以从 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')