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：**
```bash
echo fonttools > requirements.txt
echo brotli >> requirements.txt
```

**恢复cache配置：**
```yaml
- 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]：**
```yaml
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"
```

**检查仓库名：**
```yaml
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版本不兼容

### 解决方案

**检查配置文件：**
```bash
hugo config
```

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

---

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

### 可能原因

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

### 解决方案

**检查Python脚本：**
```bash
python scripts/subset-font-safe.py
```

**检查依赖版本：**
```bash
pip show fonttools
pip show brotli
```

---

## 💡 预防措施

### 1. 定期检查

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

### 2. 监控日志

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

### 3. 测试工作流

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

---

## 📞 获取帮助

### 查看GitHub文档

- [GitHub Actions文档](https://docs.github.com/en/actions)
- [workflow语法](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions)

### 查看Actions日志

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

---

**故障排除指南完成！** 🎉

**遇到问题时：**
1. 查看本文档
2. 检查Actions日志
3. 搜索GitHub文档