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` 配置可以请求开发服务器的额外来源。

appDir

启用 App Router 以使用布局、流式传输等功能。

assetPrefix

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

authInterrupts

了解如何启用实验性配置选项 `authInterrupts` 以使用 `forbidden` 和 `unauthorized` API。

basePath

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

cacheLife

了解如何在 Next.js 中设置 cacheLife 配置。

compress

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

crossOrigin

使用 `crossOrigin` 选项为 `next/script` 生成的 `script` 标签添加跨域标识。

cssChunking

使用 `cssChunking` 选项来控制 Next.js 应用中 CSS 文件的代码分割方式。

devIndicators

配置开发模式下显示当前路由上下文信息的屏幕指示器选项。

distDir

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

dynamicIO

了解如何在 Next.js 中启用 dynamicIO 实验性功能

环境变量 (env)

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

eslint

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

expireTime

为启用 ISR 的页面自定义 stale-while-revalidate 过期时间。

exportPathMap

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

generateBuildId

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

generateEtags

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

headers

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

htmlLimitedBots

指定应接收阻塞元数据的用户代理列表。

httpAgentOptions

Next.js 默认会自动使用 HTTP Keep-Alive。了解更多关于如何禁用 HTTP Keep-Alive 的信息。

图片

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

cacheHandler

配置 Next.js 用于存储和重新验证数据的缓存，以使用 Redis、Memcached 或其他任何外部服务。

inlineCss

启用内联 CSS 支持。

日志记录

配置在开发模式下运行 Next.js 时如何将数据获取日志输出到控制台。

mdxRs

使用新的 Rust 编译器在应用路由 (App Router) 中编译 MDX 文件。

onDemandEntries

配置 Next.js 在开发环境下如何处理内存中页面的创建与释放。

optimizePackageImports

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

output

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

pageExtensions

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

poweredByHeader

了解如何禁用 Next.js 默认添加的 `x-powered-by` 响应头。

部分预渲染 (PPR)

了解如何在 Next.js 中启用部分预渲染 (Partial Prerendering) 功能。

productionBrowserSourceMaps

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

reactCompiler

启用 React 编译器 (React Compiler) 以自动优化组件渲染。

reactMaxHeadersLength

React 生成并添加到响应中的标头最大长度设置。

reactStrictMode

完整的 Next.js 运行时现已兼容严格模式，了解如何启用该功能

重定向

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

rewrites

为 Next.js 应用添加重写规则。

sassOptions

配置 Sass 选项。

serverActions

配置 Next.js 应用中的服务端操作 (Server Actions) 行为。

serverComponentsHmrCache

配置服务器组件中的 fetch 响应是否在 HMR 刷新请求间进行缓存。

serverExternalPackages

将特定依赖项从服务端组件 (Server Components) 打包中排除，并使用原生 Node.js `require`。

staleTimes

了解如何覆盖客户端路由缓存 (Client Router Cache) 的失效时间。

staticGeneration*

了解如何在 Next.js 应用中配置静态生成 (Static Generation)。

taint

启用对象和值的污染 (taint) 功能。

trailingSlash

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

transpilePackages

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

turbopack

配置 Next.js 的 Turbopack 专属选项

typedRoutes

启用实验性支持以获取静态类型链接 (statically typed links)。

TypeScript

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

urlImports

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

useCache

了解如何在 Next.js 中启用 useCache 实验性标志

useLightningcss

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

viewTransition

在 App Router 中启用 React 的实验性 ViewTransition API

webpack

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

webVitalsAttribution

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

ESLint

了解如何使用和配置 ESLint 插件来捕获 Next.js 应用中的常见问题。

allowedDevOrigins

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

On this page