next.config.js 选项
Next.js 可以通过项目根目录(例如,与 package.json
同级)中的 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
// @ts-check
/**
* @type {import('next').NextConfig}
*/
const nextConfig = {
/* config options here */
}
export default nextConfig
须知:目前不支持带有
.cjs
、.cts
或.mts
扩展名的next.config
。
函数形式的配置
您也可以使用函数
// @ts-check
export default (phase, { defaultConfig }) => {
/**
* @type {import('next').NextConfig}
*/
const nextConfig = {
/* config options here */
}
return nextConfig
}
异步配置
自 Next.js 12.1.0 起,您可以使用异步函数
// @ts-check
module.exports = async (phase, { defaultConfig }) => {
/**
* @type {import('next').NextConfig}
*/
const nextConfig = {
/* config options here */
}
return nextConfig
}
阶段
phase
是加载配置的当前上下文。您可以查看可用的阶段。阶段可以从 next/constants
导入
// @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
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
basePath
basePath
在域的子路径下部署 Next.js 应用程序。bundlePagesRouterDependencies
compress
crossOrigin
crossOrigin
选项在 next/script
和 next/head
生成的 script
标签上添加 crossOrigin 标签。devIndicators
distDir
env
eslint
exportPathMap
next export
时,自定义将导出为 HTML 文件的页面。generateBuildId
generateEtags
headers
httpAgentOptions
images
onDemandEntries
optimizePackageImports
output
pageExtensions
poweredByHeader
x-powered-by
标头。在此处了解如何选择退出。productionBrowserSourceMaps
reactStrictMode
redirects
rewrites
运行时配置
serverExternalPackages
bundlePagesRouterDependencies
启用的依赖捆绑中选择退出特定的依赖项。trailingSlash
transpilePackages
turbo
typescript
urlImports
useLightningcss
webpack
webVitalsAttribution
这有帮助吗?