RaytonX Learn

加载与渲染课程内容（MDX）

本节将介绍 课程内容（MDX）如何加载与渲染，以及在工程实践中的方案选择。

方案对比

1. 存储在数据库

优点是支持实时更新,易于与业务数据整合. 缺点：编辑体验较差, 缺乏版本管理能力

2. 使用独立内容仓库（最终选择）

将课程内容存放在独立的 GitHub 仓库中, 可以有 更好的编辑体验（本地编辑）, 天然支持版本控制（Git）, 内容与业务解耦

关于 submodule：

未采用 Git Submodule，原因是：每次内容更新都需要重新部署主项目, 适合“低频更新”的场景

最终方案

  1. 通过 GitHub API 拉取 MDX 内容
  2. 使用 Next.js Cache 缓存结果
  3. 通过 Webhook + revalidate 实现按需更新

最终实现, 内容更新可立刻生效, 无需重新部署应用, 保持内容与系统解耦

实现说明

1. 环境变量配置

在项目中配置以下环境变量：

  • GITHUB_TOKEN
    创建地址：https://github.com/settings/personal-access-tokens
    用途：访问私有仓库（建议仅授予目标仓库权限）

  • GITHUB_OWNER
    仓库所属用户或组织

  • GITHUB_REPO
    内容仓库名称（如：raytonx-learn-content）

  • MDX_REVALIDATE_SECONDS（可选）

    • 不配置：默认永久缓存（需手动 revalidate）
    • 配置后：按时间自动失效

2. 加载 MDX 内容

通过 GitHub API 获取文件内容，并进行缓存控制, 参考loadMdx

3. 渲染 MDX

使用 next-mdx-remote/rsc 进行服务端渲染, 参考：LessonContent.tsx

总结

该方案的核心优势：

  • 内容独立（GitHub 仓库管理）
  • 加载高效（Next.js 缓存）
  • 更新灵活（Webhook + 按需 revalidate）