什么时候该从 JSON 升级到 MDX

JSON vs MDX：各自的优劣

JSON 数据驱动

适合：

• MVP 阶段，快速上线
• 结构化数据（Skill 列表、新闻列表）
• 内容字段简单，不需要复杂排版

局限：

• 正文是纯字符串，无法嵌入组件
• 不支持 JSX 交互组件
• 编辑体验差，大段 Markdown 塞在 JSON 里很难维护

MDX 内容管理

适合：

• 长篇教程，需要嵌入代码演示、交互组件
• 内容需要自定义布局
• 多人协作编辑

代价：

• 需要搭建 MDX 编译管线
• 构建速度变慢
• 迁移成本

什么时候迁移？

满足以下任意两条，就该考虑了：

1. 教程正文超过 500 行 Markdown
2. 需要在正文中嵌入交互组件（如代码演示）
3. 多人需要同时编辑不同教程
4. 内容版本管理变得重要

迁移步骤

1. 创建 content 目录

content/
├── tutorials/
│   ├── deploy-on-vercel.mdx
│   └── openclaw-skill-quickstart.mdx
└── news/
    └── 2026-04-20-openclaw-v16.mdx

2. 安装 MDX 支持

npm install @next/mdx @mdx-js/loader @mdx-js/react

3. 迁移内容

将 JSON 中的 content 字段提取为独立的 .mdx 文件，frontmatter 保留元数据。

4. 更新构建逻辑

使用 gray-matter 解析 frontmatter，next-mdx-remote 渲染内容。

建议：Skill 数据保持 JSON（结构化强），教程和资讯迁移到 MDX（内容灵活）。混合模式是最佳折中。