如何选择部署方式

docmd 提供四种让文档上线的方式。它们产出相同的结果 —— 一个部署到 GitHub Pages 或您所选托管服务的静态站点 —— 区别只在于您希望拥有多少控制权，以及您当前的起点。

快速决策矩阵

场景指南

“我想不到两分钟就让文档上线，零配置”

使用 GitHub App。安装它、选择您的仓库，即可完成。它会自动识别配置、生成工作流、启用 GitHub Pages 并部署 —— 您无需改动任何文件。

“我要从零搭建一个全新的文档站点”

使用 入门模板 (Starter Template)。在 GitHub 上点击 “Use this template”，更新 docmd.config.json 填入标题与 URL，启用一次 GitHub Pages，然后推送。所有环节都已预先连接好。

“我已经有 CI/CD 流水线，希望把文档加入进去”

使用 GitHub Action。在现有工作流中加入 docmd-io/deploy@v1。它能与其它步骤干净组合 —— 运行测试、构建应用、再构建文档，全部放在同一个 Job 里。

“我要部署到 Vercel、Netlify、Docker 或自己的服务器”

使用 Deployer 包。运行 npx @docmd/core deploy --vercel（或 --netlify、--docker、--nginx），即可生成与您 docmd.config.json 匹配的平台专属配置文件。

“我在 Monorepo 中，文档位于子目录”

GitHub App 与 Deployer 包 都能自动处理这种情况：前者能在仓库目录树任意位置识别配置，并自动注入正确的 --cwd 参数；后者会从当前工作目录读取配置。

如果您倾向使用 GitHub Action，请手动传入 --cwd：

- run: npx @docmd/core build --cwd packages/docs

“我想在每个 Pull Request 上预览文档”

将 GitHub Action 与 PR 预览服务结合使用（例如 Cloudflare Pages 的 Preview 部署，或自托管的预览环境）。完整的操作步骤请参阅 预览变更。

它们如何配合

这些方式并非互斥。常见的演进路径如下：

从 GitHub App 起步（最快的上线路径）
  ↓
随需求增长，定制自动生成的工作流文件
  ↓
加入 Deployer 包，生成用于自托管的 Nginx/Docker 配置
  ↓
把 Action 接入更宏观的 CI/CD 流水线

您也可以混搭使用：先用入门模板开启新项目，稍后再用 Deployer 包为 Staging 环境生成 Docker 镜像。

构建触发方式对比

延伸阅读

• GitHub Action 参考
• GitHub App 参考
• 入门模板 (Starter Template) 参考
• Deployer 包参考
• GitHub Actions CI/CD 指南
• 预览变更