next.config.js
可以通过项目根目录（例如，package.json 所在的目录）中的 next.config.js 文件以及默认导出配置 Next.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')appDir
启用 App Router 以使用布局、流式处理等功能。
assetPrefix
了解如何使用 assetPrefix 配置选项来配置您的 CDN。
authInterrupts
了解如何启用实验性的 `authInterrupts` 配置选项以使用 `forbidden` 和 `unauthorized`。
basePath
使用 `basePath` 在域的子路径下部署 Next.js 应用程序。
cacheLife
了解如何在 Next.js 中设置 cacheLife 配置。
compress
Next.js 提供 gzip 压缩来压缩渲染的内容和静态文件，它仅适用于服务器目标。在此处了解更多信息。
crossOrigin
使用 `crossOrigin` 选项在 `next/script` 生成的 `script` 标签上添加 crossOrigin 标签。
cssChunking
使用 `cssChunking` 选项来控制 CSS 文件在您的 Next.js 应用程序中如何分块。
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 将为每个页面生成 etag。在此处了解有关如何禁用 etag 生成的更多信息。
headers
向您的 Next.js 应用程序添加自定义 HTTP 标头。
httpAgentOptions
默认情况下，Next.js 将自动使用 HTTP Keep-Alive。在此处了解有关如何禁用 HTTP Keep-Alive 的更多信息。
images
next/image 加载器的自定义配置
cacheHandler
配置用于存储和重新验证数据的 Next.js 缓存，以使用任何外部服务，如 Redis、Memcached 或其他服务。
inlineCss
启用内联 CSS 支持。
logging
配置在开发模式下运行 Next.js 时如何将数据获取记录到控制台。
mdxRs
使用新的 Rust 编译器在 App Router 中编译 MDX 文件。
onDemandEntries
配置 Next.js 将如何处理和保存在内存中在开发中创建的页面。
optimizePackageImports
optimizePackageImports Next.js Config Option 的 API 参考
output
Next.js 自动跟踪每个页面所需的文件，以便轻松部署您的应用程序。在此处了解其工作原理。
pageExtensions
扩展 Pages Router 中 Next.js 在解析页面时使用的默认页面扩展名。
poweredByHeader
默认情况下，Next.js 将添加 `x-powered-by` 标头。在此处了解如何选择退出。
ppr
了解如何在 Next.js 中启用部分预渲染。
productionBrowserSourceMaps
在生产构建期间启用浏览器源地图生成。
reactCompiler
启用 React Compiler 以自动优化组件渲染。
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
了解如何覆盖客户端路由器缓存的失效时间。
staticGeneration*
了解如何在您的 Next.js 应用程序中配置静态生成。
trailingSlash
配置 Next.js 页面以解析带或不带尾部斜杠的 URL。
transpilePackages
自动转换编译和捆绑来自本地软件包（如 monorepos）或外部依赖项 (`node_modules`) 的依赖项。
turbo
使用 Turbopack 特定的选项配置 Next.js
typedRoutes
启用对静态类型链接的实验性支持。
typescript
默认情况下，Next.js 报告 TypeScript 错误。在此处了解如何选择退出此行为。
urlImports
配置 Next.js 以允许从外部 URL 导入模块。
useCache
了解如何在 Next.js 中启用 useCache 标志。
useLightningcss
启用对 Lightning CSS 的实验性支持。
webpack
了解如何自定义 Next.js 使用的 webpack 配置
webVitalsAttribution
了解如何使用 webVitalsAttribution 选项来查明 Web Vitals 问题的来源。
此页内容对您有帮助吗？