跳到内容
API 参考配置next.config.js 选项

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

experimental.adapterPath

配置 Next.js 的自定义适配器，以通过 modifyConfig 和 buildComplete 回调函数来接入构建过程。

allowedDevOrigins

使用 `allowedDevOrigins` 配置可以请求开发服务器的其他源。

assetPrefix

了解如何使用 assetPrefix 配置选项配置您的 CDN。

basePath

使用 `basePath` 将 Next.js 应用程序部署到域的子路径下。

bundlePagesRouterDependencies

为页面路由器启用自动依赖项打包

compress

Next.js 提供 gzip 压缩来压缩渲染内容和静态文件，它只适用于服务器目标。在此处了解更多信息。

crossOrigin

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

devIndicators

优化后的页面包含一个指示器，让您知道它是否正在进行静态优化。您可以在此处选择退出。

distDir

设置自定义构建目录，而不是使用默认的 .next 目录。

env

了解如何在构建时在 Next.js 应用程序中添加和访问环境变量。

exportPathMap

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

generateBuildId

配置构建 ID，用于识别您的应用程序正在服务的当前构建。

generateEtags

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

headers

向您的 Next.js 应用程序添加自定义 HTTP 头。

httpAgentOptions

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

images

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

isolatedDevBuild

使用独立的目录进行开发构建，以防止与生产构建发生冲突。

onDemandEntries

配置 Next.js 如何在开发中处理和保留创建的页面。

optimizePackageImports

optimizePackageImports Next.js 配置选项的 API 参考

output

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

pageExtensions

扩展 Next.js 在页面路由器中解析页面时使用的默认页面扩展。

poweredByHeader

Next.js 默认会添加 `x-powered-by` 头。在此处了解如何选择退出。

productionBrowserSourceMaps

在生产构建期间启用浏览器源地图生成。

experimental.proxyClientMaxBodySize

配置使用代理时最大请求正文大小。

reactStrictMode

完整的 Next.js 运行时现在符合严格模式，了解如何选择加入。

redirects

向您的 Next.js 应用程序添加重定向。

rewrites

向您的 Next.js 应用程序添加重写。

serverExternalPackages

从 `bundlePagesRouterDependencies` 启用的依赖项打包中选择退出特定的依赖项。

trailingSlash

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

transpilePackages

自动转译和打包来自本地包（如 Monorepos）或外部依赖项（`node_modules`）的依赖项。

turbopack

使用 Turbopack 特定选项配置 Next.js

typescript

Next.js 默认报告 TypeScript 错误。在此处了解如何选择退出此行为。

urlImports

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

useLightningcss

启用 Lightning CSS 的实验性支持。

webpack

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

webVitalsAttribution

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