---
description: 通过一条原生编译流水线，将可信 MDX 编译成适配可配置 JSX runtime 的 JavaScript 模块、集合元数据和确定性的 JSON manifest。
---

# 一个原生 MDX 内容编译器

给 `@amamo/mdx` 一个 MDX 目录和一份 Zod object schema。一次构建会先把 schema 转成 JSON
Schema，再校验 frontmatter、按配置的 JSX runtime（默认 React）编译每篇文档、使用 Shiki
高亮围栏代码块，并写出集合注册表、配套声明和你配置的 manifest。

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

## 选择入口

| 我想……                 | 从这里开始                         |
| ---------------------- | ---------------------------------- |
| 在 Vite 应用中编译内容 | [Vite 8](/zh-CN/vite/)             |
| 在 Next 应用中导入 MDX | [Next 16](/zh-CN/next/)            |
| 用自己的脚本驱动构建   | [编译器 API](/zh-CN/compiler-api/) |
| 查看所有配置默认值     | [配置参考](/zh-CN/configuration/)  |

## 一篇文档如何通过流水线

```text
MDX 源码 + 配置
  -> TypeScript：Zod 转 JSON Schema、发现文件、串行化操作
  -> Rust：YAML、JSON Schema、MDX 树、媒体、派生字段
  -> JavaScript：Shiki 官方主题、语法和引擎
  -> Rust：高亮模块、已校验元数据、manifest 投影、缓存记录
  -> TypeScript：collections.mjs、collections.d.ts、index.json、manifest
```

Rust 负责解析、校验、MDX 编译、manifest 投影和持久化记录。Shiki 留在 JavaScript 侧；它生成
的 HAST 经校验并注入后，Rust 才输出最终模块。直接 API、Vite 插件和 Next 包装器共用这套实现，
但每个编译器或适配器实例都有自己的状态。

## 一次构建会得到什么

- 每个被导入的 MDX 文档都有一个 JavaScript 模块，并导出 `frontmatter` 和已启用的派生字段。
- `collections.mjs`：包含文档元数据和延迟源码 import 的确定性注册表。
- `collections.d.ts`：集合注册表的配套声明产物。
- 可选 JSON manifest：支持显式字段投影、排序，以及数组或以键组织的对象输出。
- BLAKE3 寻址的缓存记录：未变化的文档可以跳过原生编译和 Shiki。

Markdown 写出的相对媒体 URL 会在全新编译通过 root 检查后变成静态 import。手写的 MDX JSX
仍会作为 MDX 的一部分编译，但其中的媒体属性不会被重写。

## 有意保留的边界

- **只接受可信内容。** MDX 编译模块在被 import 或渲染时可以执行 JavaScript。Schema 校验
  不是沙箱。
- **这是构建期编译器，不是运行时。** 宿主使用配置的 JSX runtime import 或渲染输出模块。
- **配置只能是纯数据。** 配置值加载后，函数、类实例、symbol、访问器、循环引用和非有限数字
  都会被拒绝。
- **只支持原生目标。** 不提供 JavaScript 或 WASI 回退，详见[原生目标](/zh-CN/native-targets/)。

继续阅读[快速开始](/zh-CN/getting-started/)，完成第一篇文档的编译。