# 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：自动触发（推荐）✅

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

```bash
# 发布新文章
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点自动运行

**作用：** 检查是否需要更新

**修改频率：**
```yaml
# 编辑 .github/workflows/subset-fonts.yml
schedule:
  # 每天凌晨3点
  - cron: '0 3 * * *'
  
  # 每月1号凌晨2点
  - cron: '0 2 1 * *'
```

---

## 📊 工作流步骤

### 步骤1：检出代码

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

**作用：** 下载仓库代码

---

### 步骤2：设置Python环境

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

**作用：** 安装Python 3.11

---

### 步骤3：安装依赖

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

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

---

### 步骤4：构建Hugo站点

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

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

**作用：** 生成静态HTML

---

### 步骤5：运行字体子集化

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

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

---

### 步骤6：验证优化效果

```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)
    # 检查子集字体是否更小
```

**作用：** 确保优化有效

---

### 步骤7：提交更改

```yaml
- 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：推送更改

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

---

## ⚙️ 自定义配置

### 修改触发条件

**只在特定文件变更时触发：**
```yaml
on:
  push:
    paths:
      - 'content/posts/**'
      - 'content/**/*.md'
```

---

### 修改运行频率

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

---

### 禁用定期运行

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

---

## 🐛 故障排除

### 问题1：工作流没有触发

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

---

### 问题2：Python依赖安装失败

**解决方案：**
```yaml
- 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配置完成！** 🎉

**现在可以：**
- ✅ 推送内容时自动优化字体
- ✅ 每周定期检查
- ✅ 手动触发（需要时）
- ✅ 无需手动干预