blog/themes/Ying/GITHUB_ACTIONS_GUIDE.md

🔤 字体子集化 - GitHub Actions自动化指南

🎉 好消息！

不需要每次手动执行！ 我已经为你创建了GitHub Actions工作流，可以自动完成字体子集化。

---

📋 工作流概述

工作流名称

Font Subset Optimization

触发条件

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

工作流程

内容更新 → GitHub检测到变更 → 自动构建Hugo → 运行字体子集化 → 提交优化后的字体 → 推送到main

---

🚀 使用方法

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

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

# 正常的Git工作流程
git add content/posts/new-article.md
git commit -m "feat: add new article"
git push origin main

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

查看运行状态：

1. 访问你的GitHub仓库
2. 点击 Actions 标签
3. 查看最新的工作流运行

方法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 * *'
  
  # 禁用定期运行（注释掉）
  # - cron: '0 2 * * 1'

---

🔧 配置说明

前置条件

1. GitHub仓库 - 代码已推送到GitHub
2. GitHub Actions已启用 - 默认启用
3. Hugo配置正确 - hugo.toml 或 config.toml 存在

需要修改的地方

打开 .github/workflows/subset-fonts.yml，找到这行：

if: github.repository == 'your-username/your-repo-name'

替换为你的实际仓库名：

if: github.repository == 'qunlin/blog'

如何找到你的仓库名？

• 访问你的GitHub仓库页面
• 查看URL：https://github.com/qunlin/blog
• 仓库名就是 qunlin/blog

---

📊 工作流详解

步骤1：检出代码

- name: Checkout repository
  uses: actions/checkout@v4
  with:
    fetch-depth: 0  # 获取完整历史

作用： 下载仓库代码到GitHub服务器

步骤2：设置Python环境

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

作用： 安装Python 3.11环境

步骤3：安装依赖

- name: Install dependencies
  run: |
    pip install fonttools brotli

作用： 安装字体处理工具

步骤4：检查是否需要更新

- name: Check if update needed
  id: check
  run: |
    CHANGED_FILES=$(git diff --name-only HEAD~1 HEAD -- content/ layouts/)
    if [ -n "$CHANGED_FILES" ]; then
      echo "needs_update=true" >> $GITHUB_OUTPUT
    fi

作用： 智能检测，避免不必要的运行

步骤5：构建Hugo站点

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

作用： 生成静态HTML用于字符提取

步骤6：运行字体子集化

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

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

步骤7：验证优化效果

- 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)
    if [ $SUBSET_SIZE -ge $ORIGINAL_SIZE ]; then
      echo "Skipping..."
      exit 0
    fi

作用： 确保子集字体真的更小

步骤8：提交更改

- name: Commit changes
  run: |
    git add themes/Ying/static/font/zql-v2-subset.*
    git commit -m "chore: update font subset (automated)"

作用： 保存优化后的字体文件

步骤9：推送更改

- 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%)

手动调试

如果工作流失败，可以在本地测试：

# 1. 模拟GitHub Actions环境
export GITHUB_WORKSPACE=$(pwd)
export GITHUB_SHA=$(git rev-parse HEAD)

# 2. 运行相同的步骤
pip install fonttools brotli
hugo --destination=public
python scripts/subset-font-safe.py

# 3. 检查结果
ls -lh themes/Ying/static/font/zql-v2-subset.*

---

⚙️ 自定义配置

修改触发条件

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

on:
  push:
    paths:
      - 'content/posts/**'  # 只有文章变更时
      - 'content/**/*.md'   # 只有Markdown文件

排除特定目录：

on:
  push:
    paths-ignore:
      - 'content/drafts/**'  # 排除草稿
      - 'README.md'          # 排除README

修改运行频率

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

禁用定期运行

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

添加通知

Slack通知（可选）：

- name: Notify Slack
  if: success()
  uses: 8398a7/action-slack@v3
  with:
    status: ${{ job.status }}
    text: 'Font subset updated successfully!'
  env:
    SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK }}

---

🐛 故障排除

问题1：工作流没有触发

症状： 推送代码后，Actions没有运行

解决方案：

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

问题2：Python依赖安装失败

症状： 步骤3失败

解决方案：

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

问题3：Hugo构建失败

症状： 步骤5失败

解决方案：

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

问题4：字体子集化失败

症状： 步骤6失败

解决方案：

1. 检查Python脚本是否有语法错误
2. 确保字体文件存在
3. 查看详细错误日志

问题5：推送失败

症状： 步骤9失败

原因： GitHub Actions没有写权限

解决方案：

1. 仓库设置 → Actions → General
2. Workflow permissions → 选择 Read and write permissions
3. 勾选 Allow GitHub Actions to create and approve pull requests

---

💡 最佳实践

1. 保护主分支

建议： 启用分支保护规则

• 要求Pull Request审查
• 要求状态检查通过
• 禁止强制推送

2. 监控工作流

建议： 设置失败通知

• GitHub邮件通知
• Slack/Teams集成
• 定期检查Actions页面

3. 测试工作流

建议： 在feature分支测试

# 1. 创建测试分支
git checkout -b test/font-workflow

# 2. 修改workflows文件
# 3. 推送并查看Actions
git push origin test/font-workflow

# 4. 验证无误后合并到main

4. 优化性能

建议： 使用缓存

- name: Cache Python dependencies
  uses: actions/cache@v3
  with:
    path: ~/.cache/pip
    key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }}

---

📈 工作流优势

✅ 自动化

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

✅ 智能化

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

✅ 可靠性

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

✅ 可维护性

• YAML配置清晰
• 易于自定义
• 版本控制友好

---

🎉 总结

现在的工作流程

以前： 手动运行脚本 ❌

python scripts/subset-font-safe.py  # 每次都要手动执行

现在： 全自动 ✅

git push origin main
# GitHub Actions自动完成所有工作！

你需要做的

1. ✅ 修改仓库名（在 .github/workflows/subset-fonts.yml 中）
2. ✅ 推送到GitHub
3. ✅ 启用Actions（如果还未启用）
4. ✅ 享受自动化！🎉

---

🚀 立即开始

快速设置（5分钟）

# 1. 编辑工作流文件
# 修改仓库名（如果需要）
vim .github/workflows/subset-fonts.yml

# 2. 提交并推送
git add .github/workflows/subset-fonts.yml
git commit -m "ci: add font subset automation"
git push origin main

# 3. 访问GitHub查看Actions
# https://github.com/your-username/your-repo/actions

# 4. 等待工作流完成
# 查看是否成功生成子集字体

---

文档版本： v1.0 创建时间： 2026-06-03 适用范围： Hugo博客的字体自动化优化