357 lines
5.7 KiB
Markdown
357 lines
5.7 KiB
Markdown
# 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配置完成！** 🎉
|
||
|
||
**现在可以：**
|
||
- ✅ 推送内容时自动优化字体
|
||
- ✅ 每周定期检查
|
||
- ✅ 手动触发（需要时）
|
||
- ✅ 无需手动干预
|