Next.js15 可以通过根目录的 next.config.js 进行项目配置下面是常用的配置说明和场景使用
1. 基础路由配置
1.1 redirects（重定向）
说明：
• 将访问从一个路径重定向到另一个路径
• 支持临时(307)和永久(308)重定向
• 可以包含参数匹配和通配符
使用场景：
• 网站改版后的 URL 迁移
• 多语言重定向
• 临时活动页面重定向
• 域名迁移
示例与建议：
module.exports = {
async redirects() {
return [
// 基础重定向
{
source: '/old-blog',
destination: '/blog',
permanent: true, // true = 308, false = 307
},
// 带参数的重定向
{
source: '/posts/:slug',
destination: '/blog/:slug',
permanent: true,
},
// 条件重定向
{
source: '/download',
destination: '/download/app',
permanent: false,
has: [{ type: 'header', key: 'user-agent', value: 'Mobile' }],
}
]
}
}1.2 rewrites（重写）
说明：
• 路由重写，不改变 URL 但改变实际访问路径
• 可用于 API 代理和路由代理
• 支持外部 URL 重写
使用场景：
• API 代理转发
• 微服务架构整合
• 渐进式迁移
• 隐藏复杂的 URL 结构
示例与建议：
module.exports = {
async rewrites() {
return {
beforeFiles: [
// 优先级最高的重写
{
source: '/api/v1/:path*',
destination: '/api/:path*',
}
],
afterFiles: [
// 静态文件之后的重写
{
source: '/api/proxy/:path*',
destination: 'https://api.example.com/:path*',
}
],
fallback: [
// 作为后备的重写规则
{
source: '/:path*',
destination: 'https://old-site.com/:path*',
}
]
}
}
}1.3 headers（HTTP 头）
说明：
• 自定义 HTTP 响应头
• 可以针对特定路径设置
• 支持安全相关的头部配置
使用场景：
• 配置安全策略
• 设置缓存策略
• 配置 CORS
• 自定义响应头
示例与建议：
module.exports = {
async headers() {
return [
{
source: '/:path*',
headers: [
{
key: 'X-Frame-Options',
value: 'DENY'
},
{
key: 'Content-Security-Policy',
value: "default-src 'self'"
}
]
}
]
}
}2. 构建相关配置
2.1 distDir
说明：
• 指定构建输出目录
• 默认为 .next
使用场景：
• 自定义构建输出位置
• 与其他工具集成时需要特定目录
示例与建议：
module.exports = {
distDir: 'build',
}2.2 output
说明：
• 设置构建输出模式
• 可选值：'standalone', 'export'
使用场景：
• 需要独立部署时使用 'standalone'
• 生成静态网站时使用 'export'
• Docker 部署时配置
示例与建议：
module.exports = {
output: 'standalone',
// 如果需要静态导出
// output: 'export',
}2.3 generateBuildId
说明：
• 自定义构建 ID
• 用于区分不同版本的构建
使用场景：
• 需要确定性的构建 ID
• 集成 CI/CD 时
示例与建议：
module.exports = {
generateBuildId: async () => {
// 可以使用 git commit hash
return 'my-build-id'
}
}3. 优化配置
3.1 images
说明：
• 图片优化配置
• 支持外部图片域名
• 图片大小和格式优化
使用场景：
• 需要优化图片加载性能
• 使用外部图片服务
• 控制图片质量和大小
示例与建议：
module.exports = {
images: {
domains: ['example.com'],
deviceSizes: [640, 750, 828, 1080, 1200],
imageSizes: [16, 32, 48, 64, 96],
formats: ['image/webp'],
minimumCacheTTL: 60,
remotePatterns: [
{
protocol: 'https',
hostname: 'example.com',
pathname: '/images/**',
},
],
}
}3.2 compress
说明：
• 启用响应压缩
• 减小传输大小
使用场景：
• 优化网络传输
• 减少带宽使用
示例与建议：
module.exports = {
compress: true
}4. 开发工具配置
4.1 devIndicators
说明：
• 开发环境指示器
• 显示编译和热更新状态
使用场景：
• 开发时需要清晰的状态提示
• 自定义开发体验
示例与建议：
module.exports = {
devIndicators: {
buildActivity: true,
buildActivityPosition: 'bottom-right',
}
}4.2 eslint
说明：
• ESLint 配置集成
• 代码质量检查设置
使用场景：
• 需要自定义 ESLint 规则
• 控制构建时的 lint 行为
示例与建议：
module.exports = {
eslint: {
ignoreDuringBuilds: false,
dirs: ['pages', 'components', 'lib', 'src']
}
}5. 国际化配置
5.1 i18n
说明：
• 国际化路由配置
• 语言检测和重定向
• 本地化路由
使用场景：
• 多语言网站
• 地区特定内容
• 国际化路由结构
示例与建议：
module.exports = {
i18n: {
locales: ['en', 'fr', 'de', 'zh'],
defaultLocale: 'en',
localeDetection: true,
domains: [
{
domain: 'example.com',
defaultLocale: 'en',
},
{
domain: 'example.fr',
defaultLocale: 'fr',
}
]
}
}6. 实验性功能
6.1 experimental
说明：
• 新特性试用
• 未正式发布的功能
• 可能存在变更风险
使用场景：
• 尝试最新特性
• 使用高级功能
• 测试新的开发模式
示例与建议：
module.exports = {
experimental: {
serverActions: true,
serverComponents: true,
appDir: true,
typedRoutes: true,
// 注意：实验性功能可能会改变或移除
}
}最佳实践建议
1. 环境配置分离
// next.config.js
module.exports = {
env: {
customKey: process.env.NODE_ENV === 'development'
? 'development_value'
: 'production_value'
}
}1. 条件配置
const nextConfig = {
// 基础配置...
}
if (process.env.ANALYZE === 'true') {
// 添加打包分析配置
}
module.exports = nextConfig1. 模块化配置
// config/
// - images.js
// - headers.js
// - rewrites.js
// next.config.js
const withImages = require('./config/images')
const withHeaders = require('./config/headers')
const withRewrites = require('./config/rewrites')
module.exports = withImages(withHeaders(withRewrites({
// 其他配置
})))1. 性能优化配置
module.exports = {
swcMinify: true,
compiler: {
removeConsole: process.env.NODE_ENV === 'production',
},
experimental: {
optimizeCss: true,
}
}