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

## 🎉 好消息！

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

---

## 📋 工作流概述

### 工作流名称
`Font Subset Optimization`

### 触发条件

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

### 工作流程

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

---

## 🚀 使用方法

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

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

```bash
# 正常的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`：

```yaml
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`，找到这行：

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

**替换为你的实际仓库名：**

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

**如何找到你的仓库名？**
- 访问你的GitHub仓库页面
- 查看URL：`https://github.com/qunlin/blog`
- 仓库名就是 `qunlin/blog`

---

## 📊 工作流详解

### 步骤1：检出代码
```yaml
- name: Checkout repository
  uses: actions/checkout@v4
  with:
    fetch-depth: 0  # 获取完整历史
```

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

### 步骤2：设置Python环境
```yaml
- name: Set up Python
  uses: actions/setup-python@v5
  with:
    python-version: '3.11'
```

**作用：** 安装Python 3.11环境

### 步骤3：安装依赖
```yaml
- name: Install dependencies
  run: |
    pip install fonttools brotli
```

**作用：** 安装字体处理工具

### 步骤4：检查是否需要更新
```yaml
- 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站点
```yaml
- name: Build Hugo site
  uses: peaceiris/actions-hugo@v2
  with:
    hugo-version: 'latest'
    extended: true
```

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

### 步骤6：运行字体子集化
```yaml
- name: Subset fonts
  run: python scripts/subset-font-safe.py
```

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

### 步骤7：验证优化效果
```yaml
- 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：提交更改
```yaml
- name: Commit changes
  run: |
    git add themes/Ying/static/font/zql-v2-subset.*
    git commit -m "chore: update font subset (automated)"
```

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

### 步骤9：推送更改
```yaml
- 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%)
```

### 手动调试

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

```bash
# 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.*
```

---

## ⚙️ 自定义配置

### 修改触发条件

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

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

**排除特定目录：**

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

### 修改运行频率

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

### 禁用定期运行

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

### 添加通知

**Slack通知（可选）：**

```yaml
- 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失败

**解决方案：**
```yaml
- 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分支测试

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

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

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

### 4. 优化性能

**建议：** 使用缓存

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

---

## 📈 工作流优势

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

### ✅ 智能化
- 检测内容变更
- 验证优化效果
- 避免不必要的提交

### ✅ 可靠性
- 使用官方GitHub Actions
- 完整的错误处理
- 详细的日志记录

### ✅ 可维护性
- YAML配置清晰
- 易于自定义
- 版本控制友好

---

## 🎉 总结

### 现在的工作流程

**以前：** 手动运行脚本 ❌
```bash
python scripts/subset-font-safe.py  # 每次都要手动执行
```

**现在：** 全自动 ✅
```bash
git push origin main
# GitHub Actions自动完成所有工作！
```

### 你需要做的

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

---

## 🚀 立即开始

### 快速设置（5分钟）

```bash
# 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博客的字体自动化优化