CI/CD 自动化与内容工作流

概述

自动化文档工作流确保一致的质量、减少手动错误并支持快速迭代。本节介绍如何设置 CI/CD 管道、内容迁移脚本和团队协作工作流。

问答

Q：如何使用 GitHub Actions 自动化构建？

A：创建工作流文件 .github/workflows/deploy.yml：

name: 部署文档
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm
      - run: npm ci
      - run: npm run build
      - uses: actions/upload-artifact@v4
        with:
          name: dist
          path: dist/

  deploy:
    if: github.ref == 'refs/heads/main'
    needs: build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/download-artifact@v4
        with:
          name: dist
          path: dist/
      # 部署到你的托管平台

此工作流：

每次推送和 Pull Request 时构建（尽早发现错误）
仅在推送到 main 时部署
缓存 npm 依赖以加快构建速度

Q：什么是内容迁移脚本，为什么需要它？

A：内容迁移脚本将源内容转换为文档框架所需的格式。在以下场景特别有用：

分离源和输出：原始内容保存在 source/，自动生成到 src/content/docs/
添加 frontmatter：自动生成 title、description 等元数据
编号与排序：源文件使用编号目录但输出使用清晰的路径
多语言同步：检测缺失翻译并生成占位页面

示例 package.json 钩子，在构建前运行迁移：

{
  "scripts": {
    "predev": "node scripts/migrate-content.mjs",
    "prebuild": "node scripts/migrate-content.mjs",
    "dev": "astro dev",
    "build": "astro build"
  }
}

predev 和 prebuild 钩子确保内容在 Astro 处理之前始终同步。

Q：如何设置文档变更的审查工作流？

A：使用 GitHub Pull Requests 配合分支保护：

为 main 分支设置保护规则：
- 合并前需要 Pull Request 审查
- 需要状态检查（构建必须通过）

内容变更工作流：

写作者创建分支 → 编辑 Markdown → 提交 PR
→ CI 构建预览 → 审查者批准 → 合并到 main → 自动部署

预览部署：大多数托管平台（Vercel、Netlify）自动为 Pull Request 创建预览 URL，审查者可以在合并前查看变更。

Q：如何处理文档的版本管理？

A：有三种常见方法：

方法	描述	适合
单版本	始终显示最新文档	简单产品，快速迭代团队
基于分支	每个版本是一个 Git 分支	有发布版本的软件
基于标签	使用 Starlight 的版本插件	复杂的多版本文档

对于大多数技术文档，单版本方案（始终最新）就足够了。需要时在内容本身中添加版本信息：

> [!NOTE]
> 本指南适用于固件 v2.0 及以后版本。
> v1.x 请参阅[旧版文档](/v1/guides/)。

Q：如何长期跟踪文档质量？

A：实施自动化质量检查：

链接检查：在 CI 中使用 markdown-link-check：
Terminal window
```
npx markdown-link-check -c .linkcheck.json 'source/**/*.md'
```
拼写和语法：使用 cspell 或 vale 进行自动校对
构建验证：确保站点构建无错误（CI 已覆盖）
覆盖率指标：跟踪已翻译页面数、有描述的页面数等

一个简单的 CI 组合检查：

- name: 检查链接
  run: npx markdown-link-check 'source/**/*.md'
- name: 检查拼写
  run: npx cspell 'source/**/*.md'
- name: 构建站点
  run: npm run build

正在开发商业 IoT 产品？

我们提供 ESP32 ODM 定制设计与制造服务。从原型到量产——编写这套教程的团队，可以和你一起实现。

联系我们 →