构建与发布流程

相关源文件

• .circleci/config.yml
• .github/workflows/test.yml
• .gitignore
• commands/release.go
• magefile.go
• releaser/releaser.go
• testscripts/commands/hugo__errors.txt

此页面记录了 Hugo 静态站点生成器的构建和发布流程。它涵盖了用于生成新 Hugo 版本所使用的构建工具、测试框架、版本管理和自动化发布流程。有关开发环境设置或贡献指南的详细信息，请参阅 wiki 中的相关部分。

概述

Hugo 在其构建和发布流程中结合使用了 Mage（一个基于 Go 的构建工具）、基于 Git 的版本管理和 CircleCI。该系统旨在通过自动化测试确保代码质量，同时提供简化的发布工作流。

来源： .circleci/config.yml11-111 releaser/releaser.go87-136

构建系统

Hugo 使用 Mage 作为其构建系统，它提供了用 Go 代码定义的任务，而不是使用单独的构建文件格式。

核心构建命令

命令	描述
mage hugo	构建 Hugo 二进制文件
mage hugoRace	构建启用了 race detector 的 Hugo
mage install	安装 Hugo 二进制文件
mage uninstall	卸载 Hugo 二进制文件
mage generate	生成自动生成包
mage check	运行测试和 linter

来源： magefile.go44-57 magefile.go138-154

构建配置

Hugo 的构建可以通过构建标签来自定义，以启用特定功能

构建标志在 magefile.go 中的 buildTags() 函数中定义。

来源： magefile.go44-57 magefile.go295-303

测试流程

Hugo 拥有一个全面的测试套件，该套件既能在本地运行，也能在持续集成环境中运行。

本地测试

命令	描述
mage test	运行标准测试
mage testRace	运行带有 race detector 的测试
mage test386	在 32 位模式下运行测试
mage fmt	运行 gofmt linter
mage vet	运行 go vet linter

来源： magefile.go164-217

CI 测试

测试在每次拉取请求和推送到 master 分支时会自动在 GitHub Actions 上运行。CI 流程

1. 在多个平台（Linux、Windows）上进行测试
2. 使用多个 Go 版本（1.23.x、1.24.x）进行测试
3. 包括静态分析和 linting
4. 测试带有 SCSS/SASS 支持的扩展版本

来源： .github/workflows/test.yml1-132

发布流程

Hugo 使用由 releaser 包管理的双步发布流程。

发布命令

发布流程使用一个特殊的命令来启动，该命令必须使用 release 构建标签来运行。

来源： commands/release.go26-53 releaser/releaser.go32-66

双步发布流程

发布流程

1. 第一步 - 准备发布

   • 从发布分支名称（例如 release-0.92.0）中提取版本号
   • 更新源文件中的版本号
   • 提交更改
   • 在 hugoreleaser.env 中更新标签和提交信息，供 CI/CD 管道使用

2. 第二步 - 准备下一个开发周期

   • 计算下一个开发版本（通常是递增次版本号并添加 -DEV 后缀）
   • 更新源文件中的版本号
   • 提交更改

来源： releaser/releaser.go87-181

CI/CD 流水线

自动化发布流程由 CircleCI 处理，它负责构建和发布 Hugo 版本。

CircleCI 工作流

当具有 release- 前缀的分支推送到存储库时，CircleCI 工作流将被触发。工作流包括

1. prepare_release 作业

   • 设置发布环境
   • 运行发布流程的第一步
   • 将 Git 状态缓存在缓存中，供后续作业使用

2. build_container1 作业（7 个并行实例）

   • 为大多数平台构建 Hugo 二进制文件

3. build_container2 作业

   • 为 ARM64 平台构建 Hugo 二进制文件

4. archive_and_release 作业

   • 收集构建作业的二进制文件
   • 创建归档文件
   • 将 Release 发布到 GitHub
   • 运行发布流程的第二步，为下一个开发周期做准备

来源： .circleci/config.yml11-112

版本策略

Hugo 遵循语义版本控制方案，并做了一些调整

版本格式	示例	描述
x.y.z	0.92.0	常规发布
x.y.z-DEV	0.93.0-DEV	发布之间的开发版本
x.y.z-test	0.92.0-test	测试发布（罕见）

版本信息存储在 common/hugo/version_current.go 中，并在发布过程中自动更新。

来源： releaser/releaser.go138-167 releaser/releaser.go169-181

发布产物

每次 Hugo 发布都会生成多个制品

1. 二进制可执行文件，适用于各种操作系统和架构

   • Linux (x86, x86_64, ARM)
   • macOS (x86_64, ARM64)
   • Windows (x86, x86_64)
   • FreeBSD, OpenBSD, DragonFly BSD 等

2. 归档格式

   • 适用于类 UNIX 系统的 .tar.gz
   • 适用于 Windows 的 .zip

3. 扩展变体，支持 SCSS/SASS

所有发布制品在上传到 GitHub 之前都存储在 dist 目录中。

来源： .circleci/config.yml46-47 .circleci/config.yml69-71 .circleci/config.yml86-87

手动发布流程

虽然大部分发布流程是自动化的，但创建新的 Hugo 版本仍然需要一些手动步骤

1. 创建一个具有 release-x.y.z 命名约定的新分支
2. 将分支推送到 GitHub 以触发 CircleCI 工作流
3. 监控 CircleCI 工作流以确保成功完成
4. 验证发布后添加到 GitHub 的版本
5. 在 Hugo 论坛和社交媒体上宣布发布

来源： releaser/releaser.go43-47