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

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

您也可以使用函数形式：

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 导入：

// @ts-check

const { PHASE_DEVELOPMENT_SERVER } = require('next/constants')

module.exports = (phase, { defaultConfig }) => {
  if (phase === PHASE_DEVELOPMENT_SERVER) {
    return {
      /* 此处填写仅开发环境使用的配置选项 */
    }
  }

  return {
    /* 此处填写除开发环境外其他阶段使用的配置选项 */
  }
}

注释部分就是您可以放置 next.config.js 所允许配置的位置，这些配置选项在此文件中定义。

不过，所有配置都是可选的，您无需立即理解每个配置的作用。只需在本章节中搜索您需要启用或修改的功能，文档会指导您如何操作。

请避免使用目标 Node.js 版本不支持的 JavaScript 新特性。next.config.js 不会被 Webpack、Babel 或 TypeScript 解析。

本页将详细说明所有可用的配置选项：

assetPrefix

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

basePath

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

compress

Next.js 提供了 gzip 压缩功能来压缩渲染内容和静态文件，该功能仅适用于服务端目标 (server target)。了解更多相关信息请点击此处。

crossOrigin

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

devIndicators

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

distDir

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

env

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

eslint

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

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 加载器的自定义配置

instrumentationHook

使用 instrumentationHook 选项在您的 Next.js 应用中设置监控工具

onDemandEntries

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

optimizePackageImports

关于 Next.js 配置选项 optmizedPackageImports 的 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 应用添加客户端和服务端运行时配置。

trailingSlash

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

transpilePackages

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

turbo

配置 Next.js 的 Turbopack 专属选项

TypeScript

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

urlImports

配置 Next.js 以允许从外部 URL 导入模块（实验性功能）。

webpack

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

webVitalsAttribution

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

userAgent

userAgent 辅助工具扩展了 Web Request API，提供了额外的属性和方法，用于与请求中的用户代理 (user agent) 对象进行交互。

assetPrefix

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