跳转至

网站部署指南：自动化与规范

本文档解释了 CS for NCU 项目网站的部署流程。我们采用了一套基于 GitHub Actions 的自动化工作流，以确保每一次发布都是安全、可靠且一致的。

核心理念：发布权由“系统”而非“个人”掌管

在多人协作的项目中，如果允许任何人随时从自己的电脑上手动发布网站，将会导致一系列问题：

  • 绕过审查：未经同事 review 的内容可能被直接发布上线。
  • 环境不一致：不同开发者的本地环境差异，可能导致构建出的网站效果千奇百怪。
  • 缺乏追溯：难以清晰地追溯每一次线上更新对应的是哪一次代码提交。

我们的解决方案

我们将发布权从“不确定的个人”手中，转移到了“可靠的自动化系统”上。只有当代码通过了审查并被合并到主分支 main 后，系统才会自动执行最终的正式发布。

自动化部署工作流 (deploy-docs.yml)

我们的自动化部署流程定义在仓库的 .github/workflows/deploy-docs.yml 文件中。

触发条件

工作流由两种事件触发：

  1. 推送到 main 分支 (push)：

    • 合并 PR 时：当一个 Pull Request 被合并到 main 分支，此事件触发，执行正式的网站发布。
    • 直接推送到你自己的分支时：当你将本地分支推送到你在 GitHub 上的 Fork 仓库时，此事件同样会触发。这会运行一套预览部署。

  2. 手动触发 (workflow_dispatch)：

    • 允许项目维护者在 GitHub Actions 页面手动运行部署，用于特殊情况。

核心步骤

无论由何种事件触发，工作流都将执行一套标准化的构建与部署流程：

  1. 环境准备：在一个纯净、统一的 ubuntu-latest 虚拟环境中，使用 uv 和缓存机制快速安装所有依赖。
  2. 构建网站：运行 uv run mkdocs build --strict 命令。--strict 参数会确保任何构建警告（如错误的内部链接）都导致流程失败，从而提前暴露问题。
  3. 部署到 Pages：将构建生成的 site 目录中的内容，安全地推送到触发工作流的那个仓库的 gh-pages 分支。

这对贡献者意味着什么？

你的工作流程：简单且带“预览”功能

作为贡献者，你完全不需要在本地执行任何部署命令。你的工作流程如下：

  1. 本地修改：在你自己的分支上完成内容的创作和修改。
  2. 推送进行“预部署”检查（可选但推荐）：
    • 将你的本地分支推送到你在 GitHub 上的 Fork 仓库 (git push origin your-branch-name)。
    • 这个 push 动作会触发你的 Fork 仓库中的 GitHub Actions 工作流。
    • 你可以进入你的 Fork 仓库的 Actions 页面，查看构建是否成功。 这就像一次“彩排”，能帮你提前发现本地预览时没注意到的问题（比如链接错误），确保你的代码在真实的构建环境中是健康的。
  3. 发起 Pull Request：当你确认一切无误后，向我们的主仓库发起 PR。
  4. 等待合并与正式发布：一旦你的 PR 被审查并合并到 main 分支，主仓库的 GitHub Actions 会被再次触发，这一次，它将执行最终的、正式的网站发布。

这套流程不仅保证了项目质量，也为你提供了一个强大的“云端构建”工具，让你的贡献过程更加自信和顺畅