497 lines
9.4 KiB
Markdown
497 lines
9.4 KiB
Markdown
# 🔤 字体子集化 - 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博客的字体自动化优化
|