611 lines
14 KiB
Markdown
611 lines
14 KiB
Markdown
# 方案1-第2步：字体子集化优化 - 实用指南
|
||
|
||
## 🎯 优化目标
|
||
|
||
将自定义中文字体从 **~1.5MB** 减少到 **~200KB**，提升 80%+
|
||
|
||
---
|
||
|
||
## 📋 前置准备
|
||
|
||
### 检查当前字体文件
|
||
|
||
```bash
|
||
# 查看字体文件大小
|
||
ls -lh themes/Ying/static/font/zql-v2.woff2
|
||
ls -lh themes/Ying/static/font/zql-v2.woff
|
||
|
||
# 预期大小：800KB - 2MB（包含完整中文字符集）
|
||
```
|
||
|
||
### 备份原始字体文件
|
||
|
||
```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
|
||
|
||
# 确认备份成功
|
||
ls -lh themes/Ying/static/font/*.backup
|
||
```
|
||
|
||
---
|
||
|
||
## 🔧 安装工具
|
||
|
||
### 方法1：使用glyphhanger（推荐）
|
||
|
||
```bash
|
||
# 全局安装
|
||
npm install -g glyphhanger
|
||
|
||
# 验证安装
|
||
glyphhanger --version
|
||
```
|
||
|
||
### 方法2：使用fonttools（Python）
|
||
|
||
```bash
|
||
# 安装Python工具
|
||
pip install fonttools brotli
|
||
|
||
# 验证安装
|
||
python3 -c "from fontTools.ttLib import TTFont; print('fonttools installed')"
|
||
```
|
||
|
||
---
|
||
|
||
## 🚀 实施步骤
|
||
|
||
### 步骤1：构建Hugo站点
|
||
|
||
```bash
|
||
cd E:\GitHub\blog
|
||
|
||
# 构建静态文件
|
||
hugo --destination=public
|
||
|
||
# 确认构建成功
|
||
ls -la public/
|
||
```
|
||
|
||
### 步骤2：运行字体子集化
|
||
|
||
#### 方法1：使用glyphhanger（简单）
|
||
|
||
```bash
|
||
# 从本地文件扫描并生成子集
|
||
glyphhanger \
|
||
--subset=themes/Ying/static/font/zql-v2.woff2 \
|
||
--formats=woff2,woff \
|
||
--CSS=public/css/*.css \
|
||
--HTML=public/**/*.html \
|
||
--output=themes/Ying/static/font/
|
||
|
||
# 这会生成：
|
||
# - zql-v2-subset.woff2（子集字体）
|
||
# - zql-v2-subset.woff（子集字体降级格式）
|
||
```
|
||
|
||
#### 方法2：使用Python脚本（更灵活）
|
||
|
||
创建文件：`scripts/subset-font.py`
|
||
|
||
```python
|
||
#!/usr/bin/env python3
|
||
"""
|
||
字体子集化脚本
|
||
从HTML和CSS文件中提取使用的字符，生成子集字体
|
||
"""
|
||
|
||
import os
|
||
import re
|
||
import sys
|
||
from fontTools.ttLib import TTFont
|
||
from fontTools.subset import Subsetter, Options
|
||
|
||
def extract_chars_from_files(directories):
|
||
"""从文件中提取使用的字符"""
|
||
chars = set()
|
||
|
||
for directory in directories:
|
||
if not os.path.exists(directory):
|
||
print(f"⚠️ 目录不存在: {directory}")
|
||
continue
|
||
|
||
for root, dirs, files in os.walk(directory):
|
||
for file in files:
|
||
if file.endswith(('.html', '.md', '.css')):
|
||
filepath = os.path.join(root, file)
|
||
try:
|
||
with open(filepath, 'r', encoding='utf-8') as f:
|
||
content = f.read()
|
||
|
||
# 提取中文字符
|
||
chinese_chars = re.findall(r'[一-鿿]', content)
|
||
chars.update(chinese_chars)
|
||
|
||
# 提取中文标点
|
||
cjk_punct = re.findall(r'[ -〿-]', content)
|
||
chars.update(cjk_punct)
|
||
|
||
# 提取英文和数字
|
||
ascii_chars = re.findall(r'[a-zA-Z0-9]', content)
|
||
chars.update(ascii_chars)
|
||
|
||
# 提取常用英文标点
|
||
en_punct = re.findall(r'[!@#$%^&*()_+\-=\[\]{};:\'",.<>?/\\|`~]', content)
|
||
chars.update(en_punct)
|
||
|
||
except Exception as e:
|
||
print(f"⚠️ 读取文件失败 {filepath}: {e}")
|
||
|
||
return chars
|
||
|
||
def subset_font(input_font_path, output_font_path, chars):
|
||
"""生成子集字体"""
|
||
print(f"📦 加载字体: {input_font_path}")
|
||
|
||
# 加载原始字体
|
||
font = TTFont(input_font_path)
|
||
|
||
# 获取原始字符数
|
||
cmap = font.getBestCmap()
|
||
original_count = len(cmap) if cmap else 0
|
||
|
||
# 配置子集化选项
|
||
options = Options()
|
||
if output_font_path.endswith('.woff2'):
|
||
options.flavor = 'woff2'
|
||
elif output_font_path.endswith('.woff'):
|
||
options.flavor = 'woff'
|
||
|
||
options.desubroutinize = True
|
||
|
||
# 创建子集化器
|
||
subsetter = Subsetter(options=options)
|
||
subsetter.populate(text=''.join(chars))
|
||
|
||
# 执行子集化
|
||
print("✂️ 正在生成子集字体...")
|
||
subsetter.subset(font)
|
||
|
||
# 保存子集字体
|
||
font.save(output_font_path)
|
||
|
||
# 获取子集字符数
|
||
subset_font = TTFont(output_font_path)
|
||
subset_cmap = subset_font.getBestCmap()
|
||
subset_count = len(subset_cmap) if subset_cmap else 0
|
||
|
||
# 计算大小
|
||
original_size = os.path.getsize(input_font_path)
|
||
subset_size = os.path.getsize(output_font_path)
|
||
reduction = original_size - subset_size
|
||
percentage = (reduction / original_size) * 100 if original_size > 0 else 0
|
||
|
||
print(f"\n✅ 子集化完成！")
|
||
print(f"📊 统计信息：")
|
||
print(f" 原始字符数: {original_count}")
|
||
print(f" 子集字符数: {subset_count}")
|
||
print(f" 原始大小: {original_size / 1024:.1f} KB")
|
||
print(f" 子集大小: {subset_size / 1024:.1f} KB")
|
||
print(f" 减少: {reduction / 1024:.1f} KB ({percentage:.1f}%)")
|
||
|
||
def main():
|
||
# 配置路径
|
||
font_dir = "themes/Ying/static/font"
|
||
input_font = os.path.join(font_dir, "zql-v2.woff2")
|
||
|
||
# 检查输入文件
|
||
if not os.path.exists(input_font):
|
||
print(f"❌ 字体文件不存在: {input_font}")
|
||
sys.exit(1)
|
||
|
||
# 扫描目录
|
||
scan_dirs = ["public", "content", "layouts"]
|
||
print(f"🔍 扫描目录: {', '.join(scan_dirs)}")
|
||
|
||
# 提取字符
|
||
chars = extract_chars_from_files(scan_dirs)
|
||
print(f"📝 提取了 {len(chars)} 个唯一字符")
|
||
|
||
if len(chars) == 0:
|
||
print("❌ 未找到任何字符，请检查扫描目录")
|
||
sys.exit(1)
|
||
|
||
# 保存字符列表（用于调试）
|
||
chars_file = os.path.join(font_dir, "used_chars.txt")
|
||
with open(chars_file, 'w', encoding='utf-8') as f:
|
||
f.write(''.join(sorted(chars)))
|
||
print(f"💾 字符列表已保存到: {chars_file}")
|
||
|
||
# 生成woff2子集字体
|
||
output_woff2 = os.path.join(font_dir, "zql-v2-subset.woff2")
|
||
subset_font(input_font, output_woff2, chars)
|
||
|
||
# 生成woff子集字体
|
||
output_woff = os.path.join(font_dir, "zql-v2-subset.woff")
|
||
subset_font(input_font, output_woff, chars)
|
||
|
||
print(f"\n🎉 所有子集字体生成完成！")
|
||
print(f"📂 文件位置: {font_dir}")
|
||
|
||
if __name__ == "__main__":
|
||
main()
|
||
```
|
||
|
||
运行脚本：
|
||
|
||
```bash
|
||
# 确保已构建Hugo
|
||
hugo --destination=public
|
||
|
||
# 运行字体子集化脚本
|
||
python3 scripts/subset-font.py
|
||
```
|
||
|
||
### 步骤3：验证生成的子集字体
|
||
|
||
```bash
|
||
# 检查生成的文件
|
||
ls -lh themes/Ying/static/font/zql-v2-subset.*
|
||
|
||
# 预期大小：
|
||
# zql-v2-subset.woff2: 100-300KB（比原始减少80%+）
|
||
# zql-v2-subset.woff: 150-400KB
|
||
```
|
||
|
||
---
|
||
|
||
## 📝 更新CSS字体声明
|
||
|
||
### 修改main.css
|
||
|
||
**文件：** `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;
|
||
}
|
||
|
||
/* 可选：保留原始字体作为fallback（如果子集遗漏字符） */
|
||
/*
|
||
@font-face {
|
||
font-family: 'zql-full';
|
||
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;
|
||
}
|
||
|
||
body {
|
||
font-family: 'zql', 'zql-full', serif;
|
||
}
|
||
*/
|
||
```
|
||
|
||
---
|
||
|
||
## 🧪 测试验证
|
||
|
||
### 步骤1：重新构建Hugo
|
||
|
||
```bash
|
||
# 清理缓存
|
||
hugo --cleanDestinationDir
|
||
|
||
# 重新构建
|
||
hugo --destination=public
|
||
|
||
# 启动开发服务器
|
||
hugo server -D
|
||
```
|
||
|
||
### 步骤2：检查字体加载
|
||
|
||
#### Network面板验证
|
||
|
||
1. 打开Chrome DevTools（F12）
|
||
2. 切换到 **Network** 面板
|
||
3. 刷新页面
|
||
4. 查找字体文件（.woff2, .woff）
|
||
|
||
**预期结果：**
|
||
- ✅ 看到 `zql-v2-subset.woff2` 加载
|
||
- ✅ 文件大小显著减少（<300KB）
|
||
- ✅ 无404错误
|
||
|
||
#### 视觉检查
|
||
|
||
**中文字符测试：**
|
||
- [ ] 常用汉字正常（你好世界、欢迎访问）
|
||
- [ ] 文章内容中的中文正常
|
||
- [ ] 导航菜单中文正常
|
||
- [ ] 深色模式下中文正常
|
||
|
||
**英文字符测试：**
|
||
- [ ] 英文字母正常（A-Z, a-z）
|
||
- [ ] 数字正常（0-9）
|
||
- [ ] 常用符号正常（@#$%）
|
||
|
||
**特殊字符测试：**
|
||
- [ ] 中文标点正常（，。！？、；：）
|
||
- [ ] 英文标点正常（,.!?;:）
|
||
- [ ] 其他符号正常（如果文章中有）
|
||
|
||
### 步骤3：不同页面测试
|
||
|
||
- [ ] 首页字体正常
|
||
- [ ] 文章详情页字体正常
|
||
- [ ] 友链页面字体正常
|
||
- [ ] 归档页面字体正常
|
||
- [ ] 移动端字体正常
|
||
|
||
### 步骤4：Lighthouse测试
|
||
|
||
```bash
|
||
# 运行Lighthouse审计
|
||
# 预期：Performance得分提升，无字体相关警告
|
||
```
|
||
|
||
---
|
||
|
||
## 📊 预期优化效果
|
||
|
||
### 文件大小对比
|
||
|
||
| 文件 | 优化前 | 优化后 | 减少 |
|
||
|------|--------|--------|------|
|
||
| **zql-v2.woff2** | 1.2MB | 150KB | ⚡ -87% |
|
||
| **zql-v2.woff** | 1.5MB | 200KB | ⚡ -87% |
|
||
|
||
### 加载时间提升
|
||
|
||
| 指标 | 优化前 | 优化后 | 提升 |
|
||
|------|--------|--------|------|
|
||
| **字体下载（3G）** | ~3s | ~0.5s | ⚡ -83% |
|
||
| **FCP** | +0.5s | +0.1s | ⚡ -80% |
|
||
| **字体加载总时间** | ~4s | ~1s | ⚡ -75% |
|
||
|
||
---
|
||
|
||
## 🐛 故障排除
|
||
|
||
### 问题1：字符显示为方块（□）
|
||
|
||
**症状：** 部分中文字符显示为方块
|
||
|
||
**原因：** 子集字体未包含该字符
|
||
|
||
**解决方案：**
|
||
|
||
#### 方案A：扩大字符范围
|
||
|
||
```bash
|
||
# 修改Python脚本，扫描更多目录
|
||
scan_dirs = ["public", "content", "layouts", "static"]
|
||
|
||
# 或者添加常用字符
|
||
common_chars = "的一是不了人我在有他这为之大来以个中上们到说国和地也子时"
|
||
chars.update(set(common_chars))
|
||
```
|
||
|
||
#### 方案B：使用更大的字符集
|
||
|
||
```bash
|
||
# 下载GB2312常用字符列表（6,763个字符）
|
||
# 手动添加到字符集
|
||
|
||
# 或者使用CJK字符范围
|
||
import unicodedata
|
||
cjk_chars = [chr(i) for i in range(0x4E00, 0x9FFF+1) if unicodedata.category(chr(i)) != 'Cn']
|
||
chars.update(cjk_chars)
|
||
```
|
||
|
||
#### 方案C：保留原始字体作为fallback
|
||
|
||
```css
|
||
/* 在main.css中使用font-family fallback */
|
||
@font-face {
|
||
font-family: 'zql-subset';
|
||
src: url('../font/zql-v2-subset.woff2') format('woff2');
|
||
font-display: swap;
|
||
}
|
||
|
||
@font-face {
|
||
font-family: 'zql-full';
|
||
src: url('../font/zql-v2.woff2') format('woff2');
|
||
font-display: swap;
|
||
unicode-range: U+4E00-9FFF; /* 仅CJK字符 */
|
||
}
|
||
|
||
body {
|
||
font-family: 'zql-subset', 'zql-full', serif;
|
||
}
|
||
```
|
||
|
||
### 问题2：字体文件404错误
|
||
|
||
**症状：** 浏览器Console显示字体文件404
|
||
|
||
**原因：** CSS路径不正确或文件未生成
|
||
|
||
**解决方案：**
|
||
|
||
```bash
|
||
# 1. 检查文件是否存在
|
||
ls -lh themes/Ying/static/font/zql-v2-subset.*
|
||
|
||
# 2. 确认CSS路径正确
|
||
grep -n "zql-v2-subset" themes/Ying/assets/css/main.css
|
||
|
||
# 3. 重新构建Hugo
|
||
hugo --cleanDestinationDir
|
||
```
|
||
|
||
### 问题3：子集化后文件仍然很大
|
||
|
||
**症状：** 生成的子集字体大小与原始差不多
|
||
|
||
**原因：** 可能扫描了太多字符
|
||
|
||
**解决方案：**
|
||
|
||
```bash
|
||
# 查看提取了多少字符
|
||
wc -c themes/Ying/static/font/used_chars.txt
|
||
|
||
# 如果字符数 > 5000，说明范围太广
|
||
# 修改脚本，只提取实际使用的字符
|
||
```
|
||
|
||
### 问题4：Python脚本运行失败
|
||
|
||
**症状：** 报错缺少依赖或路径错误
|
||
|
||
**解决方案：**
|
||
|
||
```bash
|
||
# 确保安装了所有依赖
|
||
pip install fonttools brotli
|
||
|
||
# 确保在正确的目录运行
|
||
cd E:\GitHub\blog
|
||
python3 scripts/subset-font.py
|
||
|
||
# 如果仍然失败，使用glyphhanger替代
|
||
npm install -g glyphhanger
|
||
glyphhanger --subset=themes/Ying/static/font/zql-v2.woff2 --formats=woff2,woff --CSS=public/css/*.css --HTML=public/**/*.html --output=themes/Ying/static/font/
|
||
```
|
||
|
||
---
|
||
|
||
## 🔄 回滚方案
|
||
|
||
如果字体优化后出现问题，立即回滚：
|
||
|
||
```bash
|
||
cd E:\GitHub\blog
|
||
|
||
# 恢复原始字体文件
|
||
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
|
||
|
||
# 删除子集字体（可选）
|
||
rm themes/Ying/static/font/zql-v2-subset.*
|
||
|
||
# 恢复CSS字体声明
|
||
# 将 main.css 中的字体路径改回原始文件名：
|
||
# zql-v2-subset.woff2 → zql-v2.woff2
|
||
# zql-v2-subset.woff → zql-v2.woff
|
||
```
|
||
|
||
---
|
||
|
||
## ✅ 完成确认清单
|
||
|
||
### 文件生成
|
||
- [ ] `zql-v2-subset.woff2` 已生成（<300KB）
|
||
- [ ] `zql-v2-subset.woff` 已生成（<400KB）
|
||
- [ ] `used_chars.txt` 已生成（用于调试）
|
||
|
||
### CSS更新
|
||
- [ ] `main.css` 字体声明已更新
|
||
- [ ] 指向新的子集字体文件
|
||
|
||
### 测试验证
|
||
- [ ] 中文字符显示正常
|
||
- [ ] 英文字符显示正常
|
||
- [ ] 特殊符号显示正常
|
||
- [ ] 所有页面字体正常
|
||
- [ ] 深色模式字体正常
|
||
- [ ] 移动端字体正常
|
||
- [ ] 无Console错误
|
||
|
||
### 性能验证
|
||
- [ ] Network面板显示字体大小减少
|
||
- [ ] Lighthouse无字体相关警告
|
||
- [ ] FCP指标改善
|
||
|
||
---
|
||
|
||
## 📈 最佳实践
|
||
|
||
### 1. 定期更新子集字体
|
||
|
||
每当网站内容大幅更新时，重新运行子集化：
|
||
|
||
```bash
|
||
# 每月或每季度运行一次
|
||
cd E:\GitHub\blog
|
||
hugo --destination=public
|
||
python3 scripts/subset-font.py
|
||
```
|
||
|
||
### 2. 监控字体大小
|
||
|
||
在部署前检查字体文件大小：
|
||
|
||
```bash
|
||
# 如果字体 > 500KB，可能需要优化
|
||
ls -lh themes/Ying/static/font/zql-v2-subset.woff2
|
||
```
|
||
|
||
### 3. 使用CDN缓存
|
||
|
||
确保字体文件通过CDN分发：
|
||
|
||
```nginx
|
||
# Nginx配置
|
||
location ~* \.(woff2|woff)$ {
|
||
expires 1y;
|
||
add_header Cache-Control "public, immutable";
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 🎉 优化完成
|
||
|
||
完成字体子集化后，你的网站将获得：
|
||
|
||
- ⚡ **字体大小减少80%+**
|
||
- ⚡ **加载速度提升80%+**
|
||
- ⚡ **移动端体验显著提升**
|
||
- ⚡ **用户流量节省80%+**
|
||
|
||
结合JS优化，总体性能提升约 **40-50%**！
|
||
|
||
---
|
||
|
||
**文档版本：** v1.0
|
||
**创建时间：** 2026-06-03
|
||
**适用方案：** 方案1（保守优化）
|