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 = nextConfigECMAScript 模块
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 和 onBuildComplete 回调钩入构建过程。
allowedDevOrigins
使用 `allowedDevOrigins` 配置可以请求开发服务器的额外源。
appDir
启用 App Router 以使用布局、流式传输等功能。
assetPrefix
了解如何使用 assetPrefix 配置选项配置您的 CDN。
authInterrupts
了解如何启用实验性的 `authInterrupts` 配置选项以使用 `forbidden` 和 `unauthorized`。
basePath
使用 `basePath` 将 Next.js 应用程序部署在域名的子路径下。
browserDebugInfoInTerminal
在开发过程中，将浏览器控制台日志和错误转发到您的终端。
cacheComponents
了解如何在 Next.js 中启用 cacheComponents 标志。
cacheLife
了解如何在 Next.js 中设置 cacheLife 配置。
compress
Next.js 提供 gzip 压缩以压缩渲染内容和静态文件，它仅适用于服务器目标。在此处了解更多信息。
crossOrigin
使用 `crossOrigin` 选项在 `next/script` 生成的 `script` 标签上添加 crossOrigin 标签。
cssChunking
使用 `cssChunking` 选项控制 Next.js 应用程序中 CSS 文件的分块方式。
devIndicators
屏幕指示器的配置选项，该指示器在开发过程中提供有关您当前正在查看的路由的上下文。
distDir
设置自定义构建目录，而不是使用默认的 .next 目录。
env
了解如何在构建时向 Next.js 应用程序添加和访问环境变量。
expireTime
为启用 ISR 的页面自定义 stale-while-revalidate 过期时间。
exportPathMap
使用 `next export` 时自定义将导出为 HTML 文件的页面。
generateBuildId
配置构建 ID，用于标识当前应用程序提供服务的构建。
generateEtags
Next.js 默认会为每个页面生成 etags。在此处了解如何禁用 etag 生成。
headers
为您的 Next.js 应用程序添加自定义 HTTP 标头。
htmlLimitedBots
指定应接收阻塞元数据的用户代理列表。
httpAgentOptions
Next.js 默认会自动使用 HTTP Keep-Alive。在此处了解如何禁用 HTTP Keep-Alive。
images
next/image 加载器的自定义配置
cacheHandler
配置用于存储和重新验证数据的 Next.js 缓存，以使用任何外部服务，如 Redis、Memcached 或其他。
inlineCss
启用内联 CSS 支持。
isolatedDevBuild
使用隔离的开发服务器构建输出，以防止与生产构建发生冲突。
logging
配置 Next.js 在开发模式下运行时数据获取的控制台日志记录方式。
mdxRs
在 App Router 中使用新的 Rust 编译器编译 MDX 文件。
onDemandEntries
配置 Next.js 如何在开发中处理和保留内存中的页面。
optimizePackageImports
optimizePackageImports Next.js 配置选项的 API 参考
output
Next.js 会自动追踪每个页面所需的文件，以便轻松部署您的应用程序。在此处了解其工作原理。
pageExtensions
扩展 Next.js 在 Pages Router 中解析页面时使用的默认页面扩展名。
poweredByHeader
Next.js 默认会添加 `x-powered-by` 标头。在此处了解如何选择退出。
productionBrowserSourceMaps
在生产构建期间启用浏览器源映射生成。
proxyClientMaxBodySize
使用代理时配置最大请求正文大小。
reactCompiler
启用 React 编译器以自动优化组件渲染。
reactMaxHeadersLength
React 发出并添加到响应中的标头的最大长度。
reactStrictMode
完整的 Next.js 运行时现在符合严格模式，了解如何选择启用
redirects
为您的 Next.js 应用程序添加重定向。
rewrites
为您的 Next.js 应用程序添加重写规则。
sassOptions
配置 Sass 选项。
serverActions
配置 Next.js 应用程序中的 Server Actions 行为。
serverComponentsHmrCache
配置 Server Components 中的 fetch 响应是否在 HMR 刷新请求之间缓存。
serverExternalPackages
选择退出 Server Components 打包中的特定依赖项，并使用原生 Node.js `require`。
staleTimes
了解如何覆盖 Client Router Cache 的失效时间。
staticGeneration*
了解如何在 Next.js 应用程序中配置静态生成。
taint
启用污染对象和值。
trailingSlash
配置 Next.js 页面是否带尾部斜杠解析。
transpilePackages
自动转译和打包来自本地包（如 Monorepos）或外部依赖项（`node_modules`）的依赖项。
turbopack
使用 Turbopack 特定选项配置 Next.js
turbopackFileSystemCache
了解如何为 Turbopack 构建启用文件系统缓存
typedRoutes
启用静态类型链接支持。
typescript
Next.js 默认报告 TypeScript 错误。在此处了解如何选择退出此行为。
urlImports
配置 Next.js 以允许从外部 URL 导入模块。
useLightningcss
启用对 Lightning CSS 的实验性支持。
viewTransition
在 App Router 中启用 React 的 ViewTransition API
webpack
了解如何自定义 Next.js 使用的 webpack 配置
webVitalsAttribution
了解如何使用 webVitalsAttribution 选项来查明 Web Vitals 问题的来源。
这有帮助吗？