配置next.config.js 选项experimental.adapterPath

experimental.adapterPath

Next.js 提供了一个实验性 API，允许您创建自定义适配器以介入构建过程。这对于需要修改 Next.js 配置或处理构建输出的部署平台或自定义构建集成非常有用。

配置

要使用适配器，请在 experimental.adapterPath 中指定适配器模块的路径

/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    adapterPath: require.resolve('./my-adapter.js'),
  },
}
 
module.exports = nextConfig

创建适配器

适配器是一个模块，它导出一个实现了 NextAdapter 接口的对象

export interface NextAdapter {
  name: string
  modifyConfig?: (
    config: NextConfigComplete,
    ctx: {
      phase: PHASE_TYPE
    }
  ) => Promise<NextConfigComplete> | NextConfigComplete
  onBuildComplete?: (ctx: {
    routes: {
      headers: Array<ManifestHeaderRoute>
      redirects: Array<ManifestRedirectRoute>
      rewrites: {
        beforeFiles: Array<ManifestRewriteRoute>
        afterFiles: Array<ManifestRewriteRoute>
        fallback: Array<ManifestRewriteRoute>
      }
      dynamicRoutes: ReadonlyArray<ManifestRoute>
    }
    outputs: AdapterOutputs
    projectDir: string
    repoRoot: string
    distDir: string
    config: NextConfigComplete
    nextVersion: string
  }) => Promise<void> | void
}

基本适配器结构

这是一个最小的适配器示例

/** @type {import('next').NextAdapter} */
const adapter = {
  name: 'my-custom-adapter',
 
  async modifyConfig(config, { phase }) {
    // Modify the Next.js config based on the build phase
    if (phase === 'phase-production-build') {
      return {
        ...config,
        // Add your modifications
      }
    }
    return config
  },
 
  async onBuildComplete({
    routes,
    outputs,
    projectDir,
    repoRoot,
    distDir,
    config,
    nextVersion,
  }) {
    // Process the build output
    console.log('Build completed with', outputs.pages.length, 'pages')
 
    // Access different output types
    for (const page of outputs.pages) {
      console.log('Page:', page.pathname, 'at', page.filePath)
    }
 
    for (const apiRoute of outputs.pagesApi) {
      console.log('API Route:', apiRoute.pathname, 'at', apiRoute.filePath)
    }
 
    for (const appPage of outputs.appPages) {
      console.log('App Page:', appPage.pathname, 'at', appPage.filePath)
    }
 
    for (const prerender of outputs.prerenders) {
      console.log('Prerendered:', prerender.pathname)
    }
  },
}
 
module.exports = adapter

API 参考

`modifyConfig(config, context)`

对于任何加载 next.config 的 CLI 命令都会调用此函数，以允许修改配置。

参数

config: 完整的 Next.js 配置对象
context.phase: 当前构建阶段（参阅阶段）

返回： 修改后的配置对象（可以是异步的）

`onBuildComplete(context)`

在构建过程完成后调用，其中包含有关路由和输出的详细信息。

参数

routes: 包含用于标头、重定向、重写和动态路由的路由清单的对象
- routes.headers: 标头路由对象数组，包含 source、sourceRegex、headers、has、missing 和可选的 priority 字段
- routes.redirects: 重定向路由对象数组，包含 source、sourceRegex、destination、statusCode、has、missing 和可选的 priority 字段
- routes.rewrites: 包含 beforeFiles、afterFiles 和 fallback 数组的对象，每个数组都包含重写路由对象，其中包含 source、sourceRegex、destination、has 和 missing 字段
- routes.dynamicRoutes: 动态路由对象数组，包含 source、sourceRegex、destination、has 和 missing 字段
outputs: 按类型组织的详细构建输出信息
projectDir: Next.js 项目目录的绝对路径
repoRoot: 检测到的仓库根目录的绝对路径
distDir: 构建输出目录的绝对路径
config: 最终的 Next.js 配置（已应用 modifyConfig）
nextVersion: 正在使用的 Next.js 版本
buildId: 当前构建的唯一标识符

输出类型

outputs 对象包含不同输出类型的数组

页面 (`outputs.pages`)

来自 pages/ 目录的 React 页面

{
  type: 'PAGES'
  id: string           // Route identifier
  filePath: string     // Path to the built file
  pathname: string     // URL pathname
  sourcePage: string   // Original source file path in pages/ directory
  runtime: 'nodejs' | 'edge'
  assets: Record<string, string>  // Traced dependencies (key: relative path from repo root, value: absolute path)
  wasmAssets?: Record<string, string>  // Bundled wasm files (key: name, value: absolute path)
  config: {
    maxDuration?: number
    preferredRegion?: string | string[]
    env?: Record<string, string>  // Environment variables (edge runtime only)
  }
}

API 路由 (`outputs.pagesApi`)

来自 pages/api/ 的 API 路由

{
  type: 'PAGES_API'
  id: string
  filePath: string
  pathname: string
  sourcePage: string   // Original relative source file path
  runtime: 'nodejs' | 'edge'
  assets: Record<string, string>
  wasmAssets?: Record<string, string>
  config: {
    maxDuration?: number
    preferredRegion?: string | string[]
    env?: Record<string, string>
  }
}

App 页面 (`outputs.appPages`)

来自 app/ 目录的 React 页面，文件名为 page.{js,ts,jsx,tsx}

{
  type: 'APP_PAGE'
  id: string
  filePath: string
  pathname: string     // Includes .rsc suffix for RSC routes
  sourcePage: string   // Original relative source file path
  runtime: 'nodejs' | 'edge'
  assets: Record<string, string>
  wasmAssets?: Record<string, string>
  config: {
    maxDuration?: number
    preferredRegion?: string | string[]
    env?: Record<string, string>
  }
}

App 路由 (`outputs.appRoutes`)

来自 app/ 的 API 和元数据路由，文件名为 route.{js,ts,jsx,tsx}

{
  type: 'APP_ROUTE'
  id: string
  filePath: string
  pathname: string
  sourcePage: string
  runtime: 'nodejs' | 'edge'
  assets: Record<string, string>
  wasmAssets?: Record<string, string>
  config: {
    maxDuration?: number
    preferredRegion?: string | string[]
    env?: Record<string, string>
  }
}

预渲染 (`outputs.prerenders`)

启用 ISR 的路由和静态预渲染

{
  type: 'PRERENDER'
  id: string
  pathname: string
  parentOutputId: string  // ID of the source page/route
  groupId: number        // Revalidation group identifier (prerenders with same groupId revalidate together)
  pprChain?: {
    headers: Record<string, string>  // PPR chain headers (e.g., 'x-nextjs-resume': '1')
  }
  parentFallbackMode?: 'blocking' | false | null  // Fallback mode from getStaticPaths
  fallback?: {
    filePath: string
    initialStatus?: number
    initialHeaders?: Record<string, string | string[]>
    initialExpiration?: number
    initialRevalidate?: number
    postponedState?: string  // PPR postponed state
  }
  config: {
    allowQuery?: string[]     // Allowed query parameters
    allowHeader?: string[]    // Allowed headers for ISR
    bypassFor?: RouteHas[]    // Cache bypass conditions
    renderingMode?: RenderingMode
    bypassToken?: string
  }
}

静态文件 (`outputs.staticFiles`)

静态资产和自动静态优化页面

{
  type: 'STATIC_FILE'
  id: string
  filePath: string
  pathname: string
}

中间件 (`outputs.middleware`)

中间件函数（如果存在）

{
  type: 'MIDDLEWARE'
  id: string
  filePath: string
  pathname: string      // Always '/_middleware'
  sourcePage: string    // Always 'middleware'
  runtime: 'nodejs' | 'edge'
  assets: Record<string, string>
  wasmAssets?: Record<string, string>
  config: {
    maxDuration?: number
    preferredRegion?: string | string[]
    env?: Record<string, string>
    matchers?: Array<{
      source: string
      sourceRegex: string
      has: RouteHas[] | undefined
      missing: RouteHas[] | undefined
    }>
  }
}