next.config.js 选项

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

next.config.js

// @ts-check
 
/** @type {import('next').NextConfig} */
const nextConfig = {
  /* config options here */
}
 
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 = {
  /* config options here */
}
 
export default nextConfig

须知: 目前不支持扩展名为 .cjs、.cts 或 .mts 的 next.config 文件。

函数形式的配置

您也可以使用函数

next.config.mjs

// @ts-check
 
export default (phase, { defaultConfig }) => {
  /**
   * @type {import('next').NextConfig}
   */
  const nextConfig = {
    /* config options here */
  }
  return nextConfig
}

异步配置

自 Next.js 12.1.0 起，您可以使用异步函数

next.config.js

// @ts-check
 
module.exports = async (phase, { defaultConfig }) => {
  /**
   * @type {import('next').NextConfig}
   */
  const nextConfig = {
    /* config options here */
  }
  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 {
      /* development only config options here */
    }
  }
 
  return {
    /* config options for all phases except development here */
  }
}

TypeScript

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

next.config.ts

import type { NextConfig } from 'next'
 
const nextConfig: NextConfig = {
  /* config options here */
}
 
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.net.cn/test',
  nextConfig: {
    async redirects() {
      return [{ source: '/test', destination: '/test2', permanent: false }]
    },
  },
})
expect(response.status).toEqual(307)
expect(getRedirectUrl(response)).toEqual('https://nextjs.net.cn/test2')

next.config.js 选项

ECMAScript 模块

函数形式的配置

异步配置

阶段

TypeScript

单元测试 (实验性)

assetPrefix

basePath

bundlePagesRouterDependencies

compress

crossOrigin

devIndicators

distDir

env

eslint

exportPathMap

generateBuildId

generateEtags

headers

httpAgentOptions

images

onDemandEntries

optimizePackageImports

output

pageExtensions

poweredByHeader

productionBrowserSourceMaps

reactStrictMode

redirects

rewrites

运行时配置

serverExternalPackages

trailingSlash

transpilePackages

turbo

typescript

urlImports

useLightningcss

webpack

webVitalsAttribution