NNext.js 中文网 GitHub

next.config.js 选项

了解 Pages Router 中 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 扩展名的 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 中的字段,不考虑 Proxy 或文件系统路由,因此生产环境中的结果可能与单元测试不同。

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')
Next.js 中文网