docs: 清理Ying主题冗余文档

- 删除20个优化相关文档 - 已整理到 docs/性能优化文档/ 文件夹 - 保留 README.md 和 archetypes/post.md
2026-06-03 13:37:53 +08:00
1 parent 6ed707704f
commit 0e17553a19
@@ -0,0 +1,356 @@
+# 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配置完成！** 🎉
+
+**现在可以：**
+- ✅ 推送内容时自动优化字体
+- ✅ 每周定期检查
+- ✅ 手动触发（需要时）
+- ✅ 无需手动干预