blog/docs/性能优化文档/09-Actions修复指南.md

09-Actions修复指南

创建日期： 2026-06-03
版本： v1.0
状态： ✅ 已修复
适用范围： GitHub Actions常见问题

---

🔴 问题1：Python依赖安装失败

错误信息

Error: No file in /home/runner/work/blog/blog matched to [**/requirements.txt or **/pyproject.toml]

原因

actions/setup-python@v5的cache功能需要requirements.txt文件

解决方案

创建requirements.txt：

echo fonttools > requirements.txt
echo brotli >> requirements.txt

恢复cache配置：

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

---

🔴 问题2：与deploy.yml冲突

问题场景

subset-fonts.yml push到main
    ↓
触发deploy.yml
    ↓
deploy.yml可能又push
    ↓
再次触发subset-fonts.yml
    ↓
无限循环！❌

解决方案

在subset-fonts.yml的commit消息中添加[skip ci]：

git commit -m "chore: update font subset (automated) [skip ci]"

原理：

• deploy.yml检查commit消息
• 如果包含[skip ci]，不会再次触发
• 避免循环触发

---

🔴 问题3：工作流没有触发

可能原因

1. Actions未启用
2. 路径过滤不正确
3. 仓库名配置错误

解决方案

检查仓库设置：

Settings → Actions → General → 选择 "Allow all actions"

检查仓库名：

if: github.repository == 'zqlit/blog'  # 确保正确

---

🔴 问题4：推送失败

错误信息

Permission denied

解决方案

修改仓库权限：

Settings → Actions → General → Workflow permissions
→ 选择 "Read and write permissions"
→ 勾选 "Allow GitHub Actions to create and approve pull requests"

---

🔴 问题5：Hugo构建失败

可能原因

1. hugo.toml配置错误
2. 主题文件缺失
3. Hugo版本不兼容

解决方案

检查配置文件：

hugo config

指定Hugo版本：

- name: Setup Hugo
  uses: peaceiris/actions-hugo@v2
  with:
    hugo-version: '0.128.2'  # 指定版本
    extended: true

---

🔴 问题6：字体子集化失败

可能原因

1. Python脚本语法错误
2. 字体文件不存在
3. 依赖版本不兼容

解决方案

检查Python脚本：

python scripts/subset-font-safe.py

检查依赖版本：

pip show fonttools
pip show brotli

---

💡 预防措施

1. 定期检查

# 每周查看Actions运行状态
# https://github.com/zqlit/blog/actions

2. 监控日志

# 查看详细日志
# Actions → 具体运行 → subset-fonts → 查看日志

3. 测试工作流

# 在feature分支测试
git checkout -b test/workflow
git push origin test/workflow

---

📞 获取帮助

查看GitHub文档

• GitHub Actions文档
• workflow语法

查看Actions日志

Actions → 具体运行 → 查看详细日志

---

故障排除指南完成！ 🎉

遇到问题时：

1. 查看本文档
2. 检查Actions日志
3. 搜索GitHub文档