跳到内容
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 功能。Webpack 或 Babel 不会解析 next.config.js。

本页记录了所有可用的配置选项

单元测试（实验性）

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

allowedDevOrigins

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

assetPrefix

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

basePath

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

bundlePagesRouterDependencies

为 Pages Router 启用自动依赖捆绑

compress

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

crossOrigin

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

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

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

output

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

pageExtensions

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

poweredByHeader

默认情况下，Next.js 将添加 x-powered-by 标头。在此处了解如何选择退出。

productionBrowserSourceMaps

在生产构建期间启用浏览器源映射生成。

reactStrictMode

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

redirects

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

rewrites

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

运行时配置

向您的 Next.js 应用程序添加客户端和服务器运行时配置。

serverExternalPackages

从 bundlePagesRouterDependencies 启用的依赖捆绑中选择退出特定的依赖项。

trailingSlash

配置 Next.js 页面以解析带或不带尾部斜杠。

transpilePackages

自动转换和捆绑来自本地包（如 monorepos）或外部依赖项 (`node_modules`) 的依赖项。

turbo

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

typescript

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

urlImports

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

useLightningcss

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

webpack

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

webVitalsAttribution

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