blog/docs/性能优化文档/08-GitHub-Actions使用指南.md

08-GitHub-Actions使用指南

创建日期： 2026-06-03
版本： v1.0
状态： ✅ 已配置完成
工作流： Font Subset Optimization

---

📋 工作流概述

工作流名称

Font Subset Optimization（字体子集优化）

工作流文件

.github/workflows/subset-fonts.yml

触发条件

1. 自动触发 - 推送到main分支且content/或layouts/有变更
2. 手动触发 - 在GitHub Actions界面手动运行
3. 定期触发 - 每周一凌晨2点自动检查

---

🚀 使用方法

方法1：自动触发（推荐）✅

无需任何操作！ 当你推送内容更新时，工作流自动运行：

# 发布新文章
git add content/posts/new-article.md
git commit -m "feat: new article"
git push origin main

# GitHub Actions自动：
# 1. 检测到content目录有变更
# 2. 构建Hugo站点
# 3. 运行字体子集化
# 4. 提交优化后的字体

查看运行状态：

访问：https://github.com/zqlit/blog/actions

---

方法2：手动触发

适用场景：

• 强制重新生成子集字体
• 修改了字体脚本
• 测试工作流

操作步骤：

1. 访问GitHub仓库 → Actions 标签
2. 选择 Font Subset Optimization
3. 点击 Run workflow
4. （可选）勾选 强制重新生成子集字体
5. 点击 Run workflow 按钮

---

方法3：定期自动运行

默认： 每周一凌晨2点自动运行

作用： 检查是否需要更新

修改频率：

# 编辑 .github/workflows/subset-fonts.yml
schedule:
  # 每天凌晨3点
  - cron: '0 3 * * *'
  
  # 每月1号凌晨2点
  - cron: '0 2 1 * *'

---

📊 工作流步骤

步骤1：检出代码

- name: Checkout repository
  uses: actions/checkout@v4
  with:
    fetch-depth: 0

作用： 下载仓库代码

---

步骤2：设置Python环境

- name: Set up Python
  uses: actions/setup-python@v5
  with:
    python-version: '3.11'
    cache: 'pip'

作用： 安装Python 3.11

---

步骤3：安装依赖

- name: Install dependencies
  run: |
    python -m pip install --upgrade pip
    pip install fonttools brotli

作用： 安装字体处理工具

---

步骤4：构建Hugo站点

- name: Build Hugo site
  uses: peaceiris/actions-hugo@v2
  with:
    hugo-version: 'latest'
    extended: true

- name: Build
  run: hugo --destination=public --minify

作用： 生成静态HTML

---

步骤5：运行字体子集化

- name: Subset fonts
  run: python scripts/subset-font-safe.py

作用： 提取字符并生成优化字体

---

步骤6：验证优化效果

- name: Verify optimization
  run: |
    ORIGINAL_SIZE=$(stat -c%s themes/Ying/static/font/zql-v2.woff2)
    SUBSET_SIZE=$(stat -c%s themes/Ying/static/font/zql-v2-subset.woff2)
    # 检查子集字体是否更小

作用： 确保优化有效

---

步骤7：提交更改

- name: Commit changes
  run: |
    git config --local user.email "github-actions[bot]@users.noreply.github.com"
    git config --local user.name "github-actions[bot]"
    git add themes/Ying/static/font/zql-v2-subset.*
    git commit -m "chore: update font subset (automated) [skip ci]"

作用： 保存优化后的字体

关键： [skip ci] 避免触发deploy.yml

---

步骤8：推送更改

- name: Push changes
  run: git push origin main

作用： 推送到GitHub仓库

---

🔍 监控和调试

查看运行状态

1. 访问GitHub仓库
2. 点击 Actions 标签
3. 查看运行列表

状态图标：

• ✅ 绿色 - 成功
• ❌ 红色 - 失败
• 🟡 黄色 - 进行中

---

查看详细日志

1. 点击具体运行记录
2. 点击 subset-fonts 任务
3. 展开每个步骤查看日志

关键日志：

✅ Font optimized: reduced 486800 bytes (39%)

---

⚙️ 自定义配置

修改触发条件

只在特定文件变更时触发：

on:
  push:
    paths:
      - 'content/posts/**'
      - 'content/**/*.md'

---

修改运行频率

schedule:
  # 每天凌晨3点
  - cron: '0 3 * * *'
  
  # 每周一和周四凌晨2点
  - cron: '0 2 * * 1,4'

---

禁用定期运行

# schedule:
#   - cron: '0 2 * * 1'

---

🐛 故障排除

问题1：工作流没有触发

解决方案：

1. 检查仓库设置 → Actions → 已启用
2. 检查路径过滤是否正确
3. 查看Actions页面的错误信息

---

问题2：Python依赖安装失败

解决方案：

- name: Install dependencies
  run: |
    python -m pip install --upgrade pip
    pip install fonttools brotli --no-cache-dir

---

问题3：Hugo构建失败

解决方案：

1. 检查hugo.toml配置
2. 确保所有主题文件存在
3. 查看Hugo错误日志

---

问题4：推送失败

原因： GitHub Actions没有写权限

解决方案：

1. 仓库设置 → Actions → General
2. Workflow permissions → 选择 Read and write permissions

---

💡 最佳实践

1. 保护主分支

建议： 启用分支保护规则

---

2. 监控工作流

建议： 设置失败通知

---

3. 测试工作流

建议： 在feature分支测试

---

📈 工作流优势

✅ 自动化

• 无需手动运行脚本
• 内容更新时自动优化
• 定期检查确保最新

✅ 智能化

• 检测内容变更
• 验证优化效果
• 避免不必要的提交

✅ 可靠性

• 使用官方GitHub Actions
• 完整的错误处理
• 详细的日志记录

---

GitHub Actions配置完成！ 🎉

现在可以：

• ✅ 推送内容时自动优化字体
• ✅ 每周定期检查
• ✅ 手动触发（需要时）
• ✅ 无需手动干预