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

单元测试（实验性）

allowedDevOrigins

appDir

assetPrefix

authInterrupts

basePath

cacheLife

compress

crossOrigin

cssChunking

devIndicators

distDir

dynamicIO

env

eslint

expireTime

exportPathMap

generateBuildId

generateEtags

headers

htmlLimitedBots

httpAgentOptions

images

cacheHandler

inlineCss

logging

mdxRs

onDemandEntries

optimizePackageImports

output

pageExtensions

poweredByHeader

ppr

productionBrowserSourceMaps

reactCompiler

reactMaxHeadersLength

reactStrictMode

redirects

rewrites

sassOptions

serverActions

serverComponentsHmrCache

serverExternalPackages

staleTimes

staticGeneration*

trailingSlash

transpilePackages

turbopack

typedRoutes

typescript

urlImports

useCache

useLightningcss

ViewTransition

webpack

webVitalsAttribution