logoNext.js 简体中文
文档博客学习
简介/API 参考文档/配置/next.config.js 配置选项

next.config.js 配置选项

Next.js 可以通过项目根目录下的 next.config.js 文件进行配置（例如位于 package.json 同级），该文件需要默认导出。

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 进行配置：

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')

allowedDevOrigins

使用 `allowedDevOrigins` 配置可以请求开发服务器的额外来源。

assetPrefix

了解如何使用 assetPrefix 配置选项来配置您的 CDN (内容分发网络)。

basePath

使用 `basePath` 将 Next.js 应用部署在域名的子路径下。

bundlePagesRouterDependencies

为 Pages Router 启用自动依赖项打包功能

compress

Next.js 提供了 gzip 压缩功能，用于压缩渲染内容和静态文件，该功能仅在使用 server 构建目标时生效。了解更多相关信息。

crossOrigin

使用 `crossOrigin` 选项可在 `next/script` 和 `next/head` 生成的 `script` 标签上添加跨域属性。

devIndicators

优化后的页面会包含一个指示器，用于显示是否正在进行静态优化。您可以在此处选择关闭该功能。

distDir

设置自定义构建目录以替代默认的 .next 目录。

env

了解如何在构建时向 Next.js 应用添加并访问环境变量。

eslint

Next.js 默认在构建过程中会报告 ESLint 错误和警告。本文将介绍如何禁用此行为。

exportPathMap

自定义在使用 `next export` 时将被导出为 HTML 文件的页面。

generateBuildId

配置构建 ID，该 ID 用于标识当前服务应用程序的构建版本。

generateEtags

Next.js 默认会为每个页面生成 etag。了解如何在此处禁用 etag 生成。

headers

为你的 Next.js 应用添加自定义 HTTP 头部

httpAgentOptions

Next.js 默认会自动使用 HTTP Keep-Alive。了解如何在此处禁用 HTTP Keep-Alive。

images

关于 next/image 加载器的自定义配置

onDemandEntries

配置 Next.js 在开发环境下如何释放和保留内存中的页面。

optimizePackageImports

关于 Next.js 配置选项 `optimizePackageImports` 的 API 参考文档

output

Next.js 会自动追踪每个页面所需的文件，以便轻松部署您的应用。了解其工作原理。

pageExtensions

扩展 Next.js 在解析 Pages Router 中的页面时使用的默认页面扩展名。

poweredByHeader

Next.js 默认会添加 `x-powered-by` 响应头。本文介绍如何禁用该功能。

productionBrowserSourceMaps

在生产构建期间启用浏览器源码映射 (source map) 生成功能

reactStrictMode

Next.js 运行时现已全面兼容严格模式 (Strict Mode)，了解如何启用该功能

重定向 (redirects)

为您的 Next.js 应用添加重定向功能。

rewrites

为你的 Next.js 应用添加重定向规则 (rewrites)。

运行时配置

为你的 Next.js 应用添加客户端与服务端运行时配置。

serverExternalPackages

从 `bundlePagesRouterDependencies` 启用的依赖捆绑中排除特定依赖项。

trailingSlash

配置 Next.js 页面解析时是否包含尾部斜杠。

transpilePackages

自动转译并打包来自本地包（如 monorepos）或外部依赖项（`node_modules`）的依赖关系。

turbo

配置 Next.js 的 Turbopack 专属选项

TypeScript

Next.js 默认会报告 TypeScript 错误。本文介绍如何禁用此行为。

urlImports

配置 Next.js 以允许从外部 URL 导入模块。

useLightningcss

启用对 Lightning CSS 的实验性支持。

webpack

了解如何自定义 Next.js 使用的 webpack 配置

webVitalsAttribution

了解如何使用 webVitalsAttribution 选项来定位 Web Vitals 问题的来源。

ESLint

Next.js 默认会在构建过程中报告 ESLint 错误和警告。本文介绍如何禁用此行为。

allowedDevOrigins

使用 `allowedDevOrigins` 配置可以请求开发服务器的额外来源。

On this page