---
description: 安装 @amamo/mdx，定义一个集合，编译一篇文档并使用生成产物。
---

# 快速开始

本指南从一个 `content/posts/hello.mdx` 文件开始，最终得到宿主可 import 的模块、集合注册表
和配套声明文件。

## 要求

- **Node.js 20.19 或更新版本。** 这是包声明的最低引擎版本。
- **受支持的原生目标。** 绑定没有 JavaScript 或 WASI 回退，详见[原生目标](/zh-CN/native-targets/)。
- **宿主应用使用 React 19。** 默认 `jsxImportSource` 是 `react`。
- **MDX 作者可信。** 编译后的 MDX 可以在宿主应用中执行 JavaScript。

## 安装

<InstallTabs packageName="@amamo/mdx" />

发布的根包会在安装时选择匹配的平台包。不要在不同操作系统、CPU 架构或 Linux libc 之间
复制 `node_modules`。

## 添加文档

创建集合目录和第一篇文档：

```mdx
---
title: 你好
---

# 你好

这篇文档由 @amamo/mdx 编译。
```

将它保存为 `content/posts/hello.mdx`。

## 定义集合

集合 schema 使用包内与 Zod 兼容的 `z.object`；其它配置值必须是可序列化的纯数据。
`defineConfig` 是向支持 TypeScript 的工具暴露配置类型的恒等辅助函数；创建编译器或适配器时
才会转换 schema、执行校验并应用默认值。

```js
// amamo.config.mjs
import { defineConfig, z } from '@amamo/mdx'

export default defineConfig({
  root: import.meta.dirname,
  collections: {
    posts: {
      directory: 'content/posts',
      schema: z.object({ title: z.string() }),
    },
  },
  manifests: {
    public: {
      output: '.amamo-mdx/public.json',
      fields: {
        key: 'key',
        slug: 'slug',
        title: 'title',
      },
    },
  },
})
```

完整构建开始前，`content/posts` 目录必须存在。集合、缓存、生成目录和 manifest 的相对路径
都从 `root` 解析。

## 选择由谁管理构建

### Vite

```ts
// vite.config.ts
import { amamoMdx } from '@amamo/mdx/vite'
import { defineConfig } from 'vite'

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

export default defineConfig({ plugins: [amamoMdx(amamo)] })
```

Vite 会执行一次完整的启动构建，直接转换被 import 的内容，并通过自己的 watcher 处理新增、
修改和删除事件。

### Next

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

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

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

Next 会在开发或生产打包前构建持久化缓存，再为 Turbopack 和 Webpack 注册只读 loader。使用
这个适配器时必须保持缓存启用。

### 直接 API

```js
// build-content.mjs
import { createCompiler } from '@amamo/mdx'

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

const compiler = await createCompiler(amamo)
try {
  const result = await compiler.build()
  console.log(result)
} finally {
  await compiler.dispose()
}
```

运行这个脚本：

```sh
node build-content.mjs
```

如果生成产物必须表示整个集合，请在 `transform()` 或 `remove()` 前先调用 `build()`。增量方法
只更新编译器当前的内存记录集，不会自行发现未出现的同级文档。

## 导入内容

在已配置的 Vite 或 Next 应用中，可以像模块一样导入 MDX：

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

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

也可以在应用代码中导入生成的集合注册表：

```ts
import { collections } from './.amamo-mdx/collections.mjs'

const hello = collections.posts.find((document) => document.slug === 'hello')
const module = await hello?.load()
```

`load()` 会 import 原始 MDX 路径，因此它必须运行在已经配置 Vite 插件或 Next loader 的宿主中。

## 生成文件

使用上面的配置，第一次构建会写出：

```text
.amamo-mdx/
  cache/
  collections.d.ts
  collections.mjs
  index.json
  public.json
```

- `collections.mjs` 包含排序后的元数据和延迟 import。
- `collections.d.ts` 是集合注册表的配套声明文件。
- `index.json` 把源码路径映射到 Next loader 使用的缓存记录；Vite 不读取它。
- `cache/` 保存可复用的编译记录，其中已经包含高亮结果。
- `public.json` 是配置的 manifest；不同的 `output` 可以把 manifest 放到其它位置。

把 `.amamo-mdx/` 加入宿主仓库的忽略文件。字节未变化的共享文件和 manifest 不会被重写。

接下来阅读[配置参考](/zh-CN/configuration/)，了解全部可用选项及其默认值。