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

此功能在 Next.js canary 版本中可用。

如果你在项目中使用 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.config.js 配置选项

ECMAScript 模块

配置为函数

异步配置

阶段

TypeScript

资源前缀

基本路径

bundlePagesRouterDependencies

压缩

crossOrigin

devIndicators

distDir

env

eslint

exportPathMap

generateBuildId

generateEtags

标头

httpAgentOptions

图像

onDemandEntries

optimizePackageImports

输出

pageExtensions

poweredByHeader

productionBrowserSourceMaps

reactStrictMode

重定向

重写规则

运行时配置

serverExternalPackages

尾部斜杠

transpilePackages

turbo

TypeScript

urlImports

useLightningcss

webVitalsAttribution

webpack