# 15-字体优化手动指南

**创建日期：** 2026-06-03  
**版本：** v1.0  
**适用场景：** 手动执行字体子集化

---

## 📋 手动操作步骤

### 步骤1：备份原始字体（2分钟）

**Windows：**
```bash
cd E:\GitHub\blog
copy themes\Ying\static\font\zql-v2.woff2 themes\Ying\static\font\zql-v2.woff2.backup
copy themes\Ying\static\font\zql-v2.woff themes\Ying\static\font\zql-v2.woff.backup
```

**Mac/Linux：**
```bash
cd E:\GitHub\blog
cp themes/Ying/static/font/zql-v2.woff2 themes/Ying/static/font/zql-v2.woff2.backup
cp themes/Ying/static/font/zql-v2.woff themes/Ying/static/font/zql-v2.woff.backup
```

---

### 步骤2：安装Python依赖（3分钟）

```bash
pip install fonttools brotli
```

**验证安装：**
```bash
python -c "from fontTools.ttLib import TTFont; print('fonttools installed')"
```

---

### 步骤3：构建Hugo站点（2分钟）

```bash
cd E:\GitHub\blog
hugo --destination=public
```

**验证构建：**
```bash
ls public/
```

---

### 步骤4：运行字体子集化（5分钟）

```bash
python scripts/subset-font-safe.py
```

**预期输出：**
```
🔤 字体子集化工具（安全版本）
==================================================
✅ 找到public目录，将扫描构建后的HTML
🔍 扫描目录: content, layouts, public
📝 提取了 2492 个唯一字符
💾 字符列表已保存到: themes/Ying/static/font\used_chars.txt
✂️  正在生成子集字体...
✅ 子集化完成！
📊 优化结果:
   子集字符数: 2485
   子集文件大小: 739.7 KB
   减少: 486.8 KB (39.7%)
🎉 所有子集字体生成成功！
```

---

### 步骤5：验证生成的文件（1分钟）

**Windows：**
```bash
dir themes\Ying\static\font\zql-v2-subset.*
```

**Mac/Linux：**
```bash
ls -lh themes/Ying/static/font/zql-v2-subset.*
```

**预期大小：**
- `zql-v2-subset.woff2`: ~757KB
- `zql-v2-subset.woff`: ~757KB

---

### 步骤6：更新CSS字体声明（3分钟）

**编辑文件：** `themes/Ying/assets/css/main.css`

**找到第1-14行的字体声明：**
```css
@font-face {
    font-family: 'zql';
    src: url('../font/zql-v2.woff2') format('woff2'),
        url('../font/zql-v2.woff') format('woff');
    font-display: swap;
    unicode-range: U+0000-007F,
        U+4E00-9FFF,
        U+2000-206F,
        U+3000-303F;
}
```

**替换为：**
```css
@font-face {
    font-family: 'zql';
    src: url('../font/zql-v2-subset.woff2') format('woff2'),
        url('../font/zql-v2-subset.woff') format('woff');
    font-display: swap;
}
```

---

### 步骤7：测试验证（5分钟）

**重新构建：**
```bash
hugo --cleanDestinationDir
hugo server -D
```

**访问：** `http://localhost:1313`

**检查清单：**
- [ ] 中文字符正常
- [ ] 英文字符正常
- [ ] 深色模式正常
- [ ] Network面板显示字体大小 ~757KB

---

### 步骤8：提交代码（2分钟）

```bash
git add themes/Ying/assets/css/main.css
git add themes/Ying/static/font/zql-v2-subset.*
git commit -m "perf: 字体子集化优化 - 减少37%"
git push origin main
```

---

## 🐛 故障排除

### 问题1：字符显示为方块

**解决方案：** 重新运行子集化脚本

### 问题2：字体文件404

**解决方案：** 检查CSS路径，清理Hugo缓存

### 问题3：Python脚本运行失败

**解决方案：** 检查Python版本和依赖

---

## 🔄 回滚方案

```bash
# 恢复原始字体
cp themes/Ying/static/font/zql-v2.woff2.backup themes/Ying/static/font/zql-v2.woff2
cp themes/Ying/static/font/zql-v2.woff.backup themes/Ying/static/font/zql-v2.woff

# 恢复CSS
git checkout themes/Ying/assets/css/main.css
```

---

## 📊 操作时间

- 步骤1：备份字体 - 2分钟
- 步骤2：安装依赖 - 3分钟
- 步骤3：构建Hugo - 2分钟
- 步骤4：运行子集化 - 5分钟
- 步骤5：验证文件 - 1分钟
- 步骤6：更新CSS - 3分钟
- 步骤7：测试验证 - 5分钟
- 步骤8：提交代码 - 2分钟

**总计：约23分钟**

---

**字体优化手动指南完成！** 🎉

**按照步骤操作即可完成字体优化！**