Next 16

Next 集成把编译和加载分开。配置包装器先构建内容集；bundler loader 再校验 index.json， 并从对应缓存记录返回编译模块。

要求

• 保持持久化缓存启用。cache: false 不会留下 loader 可读取的模块记录。
• 通过 Next import 的文件使用 .mdx。即使集合配置了其它后缀，内置 Turbopack 和 Webpack rule 仍固定为 *.mdx。
• 在受支持的原生目标上运行 next dev 和 next build。

配置 Next

// next.config.ts
import { withAmamoMdx } from '@amamo/mdx/next'

import amamo from './amamo.config.mjs'

export default withAmamoMdx(amamo)({
  reactStrictMode: true,
})

withAmamoMdx(amamo)(nextConfig) 返回异步 Next config 函数。之后由 Next 使用当前 phase 和 { defaultConfig } 调用它；它不会立即返回已经解析的配置。

内层输入可以是配置对象、Promise 或配置函数：

import { withAmamoMdx } from '@amamo/mdx/next'

import amamo from './amamo.config.mjs'

export default withAmamoMdx(amamo)(async (_phase, { defaultConfig }) => ({
  ...defaultConfig,
  images: {
    remotePatterns: [{ hostname: 'cdn.example.com', protocol: 'https' }],
  },
}))

包装器会 await 输入，保留其中的字段和已有 webpack callback，再加入自己的 Turbopack 与 Webpack rule。

Phase 行为

一次 wrapper 调用拥有一个延迟编译器和一个共享 build Promise。请在 Next config 中创建一次 wrapper，而不是为单个请求重复创建。

Loader 流程

同一个 loader 会注册到：

• turbopack.rules['*.mdx']，并把输出声明为 JavaScript。
• Webpack 中 test: /\.mdx$/ 的 module rule。

对于每个被 import 的源码路径，loader 会：

1. 读取 <generatedDirectory>/index.json。
2. 检查其中的配置指纹与 wrapper 当前的归一化配置一致。
3. 找到源码缓存键，并校验它是否为十六进制。
4. 读取对应 JSON 缓存记录。
5. 校验记录键并返回编译后的 module 字符串。

任何不一致都会以 AMAMO_NEXT_CACHE_MISS 拒绝，并要求执行协调构建。Loader 是只读的；解析、 Shiki、manifest 写入和缓存清理都由 wrapper 拥有的编译器完成。

导入 MDX

import Post, { frontmatter } from '../content/posts/hello.mdx'

export default function Page() {
  return (
    <main>
      <h1>{frontmatter.title}</h1>
      <Post />
    </main>
  )
}

Turbopack 和 Webpack 读取相同的索引和记录格式。

开发期行为

在开发模式中，编译器会递归监听 config.root。属于集合的新增或修改会执行 transform，删除 已知记录会执行 remove。这会独立于 Next 的文件 watcher 刷新缓存和生成产物；两个 watcher 之间没有时序协调机制。

修改配置本身后请重启 next dev。调用 withAmamoMdx(amamo) 时，wrapper 的归一化配置、 指纹和 loader 选项就已经固定。

故障排查