next.config

2026年9月6日

next.config.ts 是框架开关。这里不抄完整手册，只记项目里真会碰到的。全表见 next.config.js。

按 phase 分支

默认导出可以是函数，参数是构建阶段：

import type { NextConfig } from "next";
import { PHASE_DEVELOPMENT_SERVER } from "next/constants";

export default function config(phase: string): NextConfig {
  const nextConfig: NextConfig = { reactCompiler: false };
  if (phase === PHASE_DEVELOPMENT_SERVER) {
    nextConfig.reactCompiler = true;
  }
  return nextConfig;
}
ts

其它常量：PHASE_PRODUCTION_BUILD、PHASE_PRODUCTION_SERVER、PHASE_EXPORT、PHASE_TEST。

端口

配置文件里没有 port。写在脚本里：

{
  "scripts": {
    "dev": "next dev -p 8888",
    "start": "next start -p 9999"
  }
}
json

静态导出、图片

output: "export"、trailingSlash、images.remotePatterns / formats / deviceSizes 见 静态导出 和 Image。

headers

给匹配路径加响应头，CORS、安全头都走这里：

const nextConfig: NextConfig = {
  async headers() {
    return [
      {
        source: "/:path*",
        headers: [
          { key: "Access-Control-Allow-Origin", value: "*" },
          {
            key: "Access-Control-Allow-Methods",
            value: "GET, POST, PUT, DELETE, OPTIONS",
          },
        ],
      },
    ];
  },
};
ts

source 支持精确路径和动态段。生产把 * 换成明确源。

assetPrefix 和 basePath

assetPrefix：静态资源挂到 CDN。

assetPrefix: "https://cdn.example.com";
ts

/_next/static/... 会变成 https://cdn.example.com/_next/static/...。

basePath：整站挂在子路径，比如 GitHub Pages 的 /repo：

basePath: "/docs",
async redirects() {
  return [
    {
      source: "/",
      destination: "/docs",
      basePath: false,
      permanent: false,
    },
  ];
},
ts

Link href="/home" 会自动变成 /docs/home。redirects 里若再让框架加一次前缀，会变成 /docs/docs，所以这里 basePath: false。

其它常用开关

项作用
compressgzip / brotli，默认开
logging.fetches.fullUrl开发时打印完整 fetch URL
pageExtensions允许 md / mdx 当页面
devIndicators关掉或挪开发角标
generateEtags静态资源 ETag，默认开
turbopack.rules给 Turbopack 加 loader，例如 less
turbopack: {
  rules: {
    "*.less": { loaders: ["less-loader"], as: "*.css" },
  },
},
ts

下一篇：身份验证，用 Better Auth 一类库接邮箱和 OAuth。

参考文档