告别 Font-Spider：使用自定义脚本实现 Astro 博客字体精准子集化

为什么要迁移？#

在 Astro 博客中，中文字体动辄几 MB 的体积是影响首屏加载速度的“元凶”。之前我一直使用 Font-Spider (字蛛) 来进行子集化裁剪，但随着项目的深度魔改，一些难以调和的矛盾开始显现：

停止维护：font-spider 已经多年未更新，对现代 CSS 特性支持较弱。
路径映射地狱：在处理构建后的绝对路径（如 /MiSans-Regular.ttf）时，font-spider 常找不到文件，必须依赖复杂的 --map 参数。（这也是许多教程没有介绍的，虽然我之前写的脚本解决了这个问题但是毕竟这个项目都不知道多少年没更新了）
黑盒操作：难以集成到现代 TypeScript 脚本流中，报错信息模糊。

为了彻底解决这些问题，我决定手动编写一个基于 subset-font 的裁剪脚本。（才怪，AI是主力，我只是记录一下过程）

迁移步骤#

第一步：清理门户#

首先，为了避免更多问题，需要移除已经过时的工具和旧脚本。（不要在没有git仓库或备份时执行，这是危险行为！）在你的终端执行：

1
# 移除旧依赖
2
pnpm remove font-spider
3

4
# 移除之前的旧脚本文件（如果有）
5
rm scripts/compress-font.js

第二步：引入现代动力#

我们需要几个核心库来驱动新的裁剪脚本：

subset-font：真正的字体裁剪核心，支持 TTF/OTF/WOFF。
he：用于处理 HTML 中的实体字符（如   解码回空格）。
tsx：让我们直接运行 TypeScript 编写的脚本。

1
pnpm add -D subset-font he tsx

第三步：编写核心裁剪脚本 `font-subset.ts`#

在 scripts/ 目录下创建 font-subset.ts。这个脚本的逻辑非常清晰：

扫描 dist/ 目录下的所有 HTML 文件。
提取页面中所有可见的文字，并进行去重。
读取原始字体文件。
裁剪使用 subset-font 根据提取的文字集生成新的字体文件并覆盖。

以下是实现：

1
import fs from 'node:fs';
2
import path from 'node:path';
3
import subsetFont from 'subset-font';
4
import he from 'he';
5
import { fontConfig } from '../src/configs/font';
6

7
const DIST_DIR = 'dist';
8

9
/**
10
 * 递归获取目录下所有 HTML 文件
11
 */
12
function getHtmlFiles(dir: string): string[] {
13
    let results: string[] = [];
14
    if (!fs.existsSync(dir)) return [];
15
    const list = fs.readdirSync(dir);
16
    for (const file of list) {
17
        const fullPath = path.join(dir, file);
18
        const stat = fs.statSync(fullPath);
19
        if (stat && stat.isDirectory()) {
20
            results = results.concat(getHtmlFiles(fullPath));
21
        } else if (file.endsWith('.html')) {
22
            results.push(fullPath);
23
        }
24
    }
25
    return results;
26
}
27

28
/**
29
 * 从 HTML 中提取所有可见文本，并解码 HTML 实体
30
 */
31
function extractTextFromHtml(html: string): string {
32
    // 1. 移除脚本标签内容
33
    let content = html.replace(/<script\b[^<]*(?:(?!<\/script>)<[^<]*)*<\/script>/gi, '');
34
    // 2. 移除样式标签内容
35
    content = content.replace(/<style\b[^<]*(?:(?!<\/style>)<[^<]*)*<\/style>/gi, '');
36
    // 3. 移除所有 HTML 标签
37
    content = content.replace(/<[^>]+>/g, ' ');
38
    // 4. 解码 HTML 实体 (如 &nbsp; -> 空格)
39
    content = he.decode(content);
40
    return content;
41
}
42

43
async function main() {
44
    console.log('\x1b[36m%s\x1b[0m', '>> Starting modern font subsetting (replacement for font-spider)...');
45

46
    if (!fontConfig.enable || fontConfig.fonts.length === 0) {
47
        console.log('Font subsetting disabled or no fonts configured in src/configs/font.ts.');
48
        return;
49
    }
50

51
    // 1. 收集所有 HTML 中的文字
52
    const htmlFiles = getHtmlFiles(DIST_DIR);
53
    if (htmlFiles.length === 0) {
54
        console.warn(`Dist directory '${DIST_DIR}' not found or contains no HTML files. Did you run build?`);
55
        return;
56
    }
57

58
    const charSet = new Set<string>();
59
    // 添加一些基础字符保证渲染（标点、数字等基本需求）
60
    "0123456789.+-:()[]{} ".split('').forEach(c => charSet.add(c));
61

62
    for (const file of htmlFiles) {
63
        const html = fs.readFileSync(file, 'utf-8');
64
        const text = extractTextFromHtml(html);
65
        for (const char of text) {
66
            // 过滤掉不可见字符和空白，保留有意义的字符
67
            if (char.trim() || char === ' ') charSet.add(char);
68
        }
69
    }
70

71
    const allChars = Array.from(charSet).sort().join('');
72
    console.log(`Extracted ${charSet.size} unique characters from ${htmlFiles.length} files:`);
73
    console.log(`\x1b[90m${allChars}\x1b[0m`); // 使用灰色输出详细字符集内容内容
74

75
    // 2. 遍历配置进行子集化
76
    for (const font of fontConfig.fonts) {
77
        const relativePath = font.src.startsWith('/') ? font.src.slice(1) : font.src;
78
        const fontPath = path.join(DIST_DIR, relativePath);
79

80
        if (!fs.existsSync(fontPath)) {
81
            console.error(`Font file not found in dist: ${fontPath}`);
82
            continue;
83
        }
84

85
        console.log(`Processing font: ${font.name} (${fontPath})`);
86

87
        try {
88
            const originalBuffer = fs.readFileSync(fontPath);
89

90
            // 执行子集化
91
            // subset-font 默认会根据输入 buffer 自动识别格式 (TTF/OTF/WOFF)
92
            // targetFormat 设为 'truetype' 对应 .ttf 格式
93
            const subsetBuffer = await subsetFont(originalBuffer, allChars, {
94
                targetFormat: 'truetype'
95
            });
96

97
            // 检查压缩效果
98
            const oldSize = (originalBuffer.length / 1024).toFixed(2);
99
            const newSize = (subsetBuffer.length / 1024).toFixed(2);
100

101
            fs.writeFileSync(fontPath, subsetBuffer);
102
            console.log(`\x1b[32m  ✔ ${font.name}: ${oldSize}KB -> ${newSize}KB (Reduced by ${((1 - subsetBuffer.length / originalBuffer.length) * 100).toFixed(1)}%)\x1b[0m`);
103
        } catch (err) {
104
            console.error(`  ✘ Failed to subset ${font.name}:`, err);
105
        }
106
    }
107

108
    console.log('\x1b[32m%s\x1b[0m', '>> Font subsetting completed successfully.');
109
}
110

111
main().catch(err => {
112
    console.error('Fatal error during font subsetting:', err);
113
    process.exit(1);
114
});

第四步：集成到构建#

最后一步，修改 package.json，让脚本在 astro build 完成后自动触发。

找到 scripts 部分，更新 build 命令：

1
{
2
  "scripts": {
3
    "build": "pnpm run validate-config && astro build && pagefind --site dist && tsx scripts/font-subset.ts"
4
  }
5
}

诶之前清理的时候好像没更新package.json？不管了现在没事了，如果你在清理之后构建失败可以检查下。

还有一件事：validate-config是我自己加的基于ZOD的配置检验，你的博客可能没有，如果没有就去掉这个脚本执行。一切以你自己的博客为准，在最后添加tsx执行脚本就行了。

现在，每次执行 pnpm build，系统都会：

验证配置。
构建 Astro 站点。
生成搜索索引。
自动提取全站文字并把几 MB 的字体裁剪到几十 KB。

现在你可以刷新一下你的博客，测试字体了。如果你在迁移过程中遇到问题，欢迎在下方评论区交流。

Wtada233's Blog

为什么要迁移？#

迁移步骤#

第一步：清理门户#

第二步：引入现代动力#

第三步：编写核心裁剪脚本 `font-subset.ts`#

第四步：集成到构建#

相关文章

Wtada233's Blog

为什么要迁移？#

迁移步骤#

第一步：清理门户#

第二步：引入现代动力#

第三步：编写核心裁剪脚本 font-subset.ts#

第四步：集成到构建#

相关文章

第三步：编写核心裁剪脚本 `font-subset.ts`#