中文字体部署与字蛛(Font-Spider)压缩教程

我敢保证这是我做的最有用的教程了，堪称保姆级，如果你看不懂请自行Github#

中文字体通常体积巨大（动辄几 MB），直接在网页中使用会导致加载缓慢，严重影响用户体验。本文将介绍如何使用 Font-Spider (字蛛) 对中文字体进行子集化压缩，只保留网页中实际用到的字符，从而将字体体积缩减到几十 KB。

其实我做这个教程还有一个目的：彻底解决网上各种font-spider教程的乱象，—map参数是不教的，html是手动写的，网页全是静态的，静态到页面生成器都没有只有手写html，我就想问真实项目能用吗？#

注意这个教程基于Fuwari，你要是不用Fuwari也可以参考，脚本使用NodeJS编写。 MiSans-Regular换自己字体！

准备：了解font-spider原理#

font-spider很久没有更新，所以pnpm提示过时依赖没事。

这个工具会先查找指定的文件/文件夹中的所有指定的文件（一般是html），然后把html中的style中的font-face标签提取，找到字体，并根据style标签中字体的应用范围查找所有文字并从字体提取然后重新打包

所以其原理就是只保留用的文字，简称子集化。

当然，还有个大问题：web路径怎么办？

举个我遇到的例子，我需要指定字体为/MiSans-Regular.ttf这个路径才能让所有页面都读取到我的字体，但是font-spider不认，去系统根目录找字体（我不知道Windows下会怎样）

这种情况下，我们就需要用到后文的—map参数。这个参数格式为—map “原路径,替换路径”，如—map “/foobar.ttf,dist/foobar.ttf”，这样就能解决这令人绝望的问题。

环节一：准备字体文件#

首先，需要准备好你的字体文件（ .ttf 格式）。为了让 Astro 构建后的站点能够直接访问到字体，我们需要将其放入 public 目录。

例如，将 MiSans-Regular.ttf 放入 public/ 根目录：

1
/public
2
  ├── MiSans-Regular.ttf
3
  └── ...

同时，我们需要一个配置文件来管理字体信息。创建 src/configs/font.ts：

1
// 字体配置
2
export const fontConfig = {
3
    // 启用自定义字体
4
    enable: true,
5
    // 字体列表
6
    fonts: [
7
        {
8
            name: "MiSans-Regular",
9
            src: "/MiSans-Regular.ttf", // 相对于 public 目录
10
            type: "truetype",
11
            weight: "normal",
12
            style: "normal",
13
            display: "swap",
14
        },
15
    ],
16
    // 全局字体族设置
17
    family:
18
        "'MiSans-Regular', -apple-system, BlurMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'MicrosoftO Sans', 'Microsoft YaHei', 'WenQuanYi Micro Hei', sans-serif",
19
};

环节二：添加 Font-Spider 依赖#

我们需要安装 font-spider 作为开发依赖。（不然你觉得呢，我遇见一堆教程都是npm install -g，看得我都想问作者换电脑怎么办）

它可以分析本地 HTML 文件，提取其中使用的文字，并从原始字体中删除未使用的字符。

在项目根目录下运行：

1
pnpm add -D font-spider

或者在 package.json 中手动添加并安装：（不建议）

1
"devDependencies": {
2
  "font-spider": "^1.3.5",
3
  // ...
4
}

环节三：配置全局样式 (关键步骤)#

为了让 Font-Spider 正确识别 HTML 中的字体用法，我们需要在页面中显式声明 @font-face 并应用 font-family。

在 Astro 中，我们在全局布局文件 src/layouts/Layout.astro 中使用 <style is:global> 来注入这些样式。关键在于 is:global 属性，它确保样式不会被 Astro 作用域隔离，从而能应用到 body 上并被 Font-Spider 爬取到。

修改 src/layouts/Layout.astro，引入 fontConfig 并在 <style is:global> 中动态生成 CSS：

1
---
2
import { fontConfig } from "@configs/font";
3
// ... 其他 import
4
---
5

6
<!-- ... 其他 head 内容 ... -->
7

8
<style is:global set:html={`
9
${fontConfig.enable ? fontConfig.fonts.map((font) => `
10
    @font-face {
11
        font-family: '${font.name}';
12
        src: url('${font.src}') format('${font.type}');
13
        font-weight: ${font.weight};
14
        font-style: ${font.style};
15
        font-display: ${font.display};
16
    }
17
`).join('') : ''}
18
    body {
19
        font-family: ${fontConfig.family};
20
    }
21
`}></style>
22

23
<!-- ... body 内容 ... -->

原理解析：

@font-face 声明了自定义字体，src 指向我们放在 public 目录下的字体文件（构建后会在根目录）。
body { font-family: ... } 将该字体应用到全局。
Font-Spider 扫描 HTML 时，会查找这两个声明，并匹配页面文本中使用了该 font-family 的字符。

环节四：编写自动压缩脚本#

最后，我们需要一个脚本在项目构建完成后自动运行 Font-Spider。

创建 scripts/compress-font.js，以下是完整的脚本代码：

1
import fs from 'node:fs';
2
import path from 'node:path';
3
import { execSync } from 'node:child_process';
4

5
const DIST_DIR = 'dist';
6
const CONFIG_PATH = 'src/configs/font.ts';
7

8
function main() {
9
    console.log('\x1b[36m%s\x1b[0m', '>> Starting intelligent font-spider compression...');
10

11
    // 1. Check Config Existence
12
    if (!fs.existsSync(CONFIG_PATH)) {
13
        console.warn(`Config file not found at ${CONFIG_PATH}, skipping font compression.`);
14
        return;
15
    }
16

17
    // 2. Read and Parse Config
18
    const configContent = fs.readFileSync(CONFIG_PATH, 'utf-8');
19

20
    // Check if enabled
21
    const enableMatch = configContent.match(/enable:\s*(true|false)/);
22
    if (enableMatch && enableMatch[1] === 'false') {
23
        console.log('Custom fonts are disabled in config. Skipping.');
24
        return;
25
    }
26

27
    // Extract fonts
28
    const fontSrcs = [];
29
    // Match the fonts array block
30
    const fontsMatch = configContent.match(/fonts:\s*\[([\s\S]*?)\]/);
31
    if (fontsMatch) {
32
        const fontsBlock = fontsMatch[1];
33
        // Match src properties: src: "..." or src: '...'
34
        const srcMatches = fontsBlock.matchAll(/src:\s*["']([^"']+)["']/g);
35
        for (const match of srcMatches) {
36
            fontSrcs.push(match[1]);
37
        }
38
    }
39

40
    if (fontSrcs.length === 0) {
41
        console.log('No custom fonts found in config to compress.');
42
        return;
43
    }
44

45
    console.log(`Found ${fontSrcs.length} font(s) to compress: ${fontSrcs.join(', ')}`);
46

47
    // 3. Find HTML files recursively
48
    if (!fs.existsSync(DIST_DIR)) {
49
        console.error(`Dist directory '${DIST_DIR}' not found. Did you run build?`);
50
        process.exit(1);
51
    }
52

53
    // recursive: true requires Node 20.1.0+
54
    let htmlFiles = [];
55
    try {
56
        const files = fs.readdirSync(DIST_DIR, { recursive: true });
57
        htmlFiles = files
58
            .filter(file => file.endsWith('.html'))
59
            .map(file => path.join(DIST_DIR, file));
60
    } catch (e) {
61
        // Fallback for older Node versions if necessary (though package.json says >=20)
62
        console.warn('fs.readdir recursive failed, falling back to manual recursion.');
63
        htmlFiles = findFilesRecursive(DIST_DIR);
64
    }
65

66
    if (htmlFiles.length === 0) {
67
        console.log('No HTML files found in dist directory.');
68
        return;
69
    }
70
    console.log(`Found ${htmlFiles.length} HTML files.`);
71

72
    // 4. Construct Arguments
73
    // --map '/url/path,local/path'
74
    const mapArgs = fontSrcs.map(src => {
75
        // Remove leading slash for local path construction
76
        const relativePath = src.startsWith('/') ? src.slice(1) : src;
77
        const localPath = path.join(DIST_DIR, relativePath);
78
        // Map format: '/web/path,local/fs/path'
79
        return `--map '${src},${localPath}'`;
80
    }).join(' ');
81

82
    // 5. Execute font-spider
83
    // We pass the list of files.
84
    // If the list is too long for the shell, we might need to handle it differently,
85
    // but for a blog site, it should be fine.
86
    const fileListStr = htmlFiles.map(f => `"${f}"`).join(' ');
87
    const command = `npx font-spider ${fileListStr} ${mapArgs}`;
88

89
    console.log('Executing font-spider...');
90
    try {
91
        execSync(command, { stdio: 'inherit', maxBuffer: 1024 * 1024 * 50 });
92
        console.log('\x1b[32m%s\x1b[0m', '>> Font compression completed successfully.');
93
    } catch (error) {
94
        console.error('\x1b[31m%s\x1b[0m', '>> Font compression failed.');
95
        process.exit(1);
96
    }
97
}
98

99
function findFilesRecursive(dir) {
100
    let results = [];
101
    const list = fs.readdirSync(dir);
102
    list.forEach(file => {
103
        const fullPath = path.join(dir, file);
104
        const stat = fs.statSync(fullPath);
105
        if (stat && stat.isDirectory()) {
106
            results = results.concat(findFilesRecursive(fullPath));
107
        } else {
108
            if (fullPath.endsWith('.html')) results.push(fullPath);
109
        }
110
    });
111
    return results;
112
}
113

114
main();

最后，修改 package.json 的 build 命令，在 astro build 之后运行这个脚本：

1
"scripts": {
2
  "build": "astro build && pagefind --site dist && node scripts/compress-font.js",
3
  // ...
4
}

这样，每次执行 pnpm build 时，系统会自动：

构建静态站点到 dist 目录。
compress-font.js 扫描 dist 中的所有 HTML。
Font-Spider 分析 HTML 内容，压缩 dist 目录下的字体文件。

现在，你的博客就拥有了体积小巧且加载迅速的中文字体了！如果你遇到其他问题，可以体验下我新部署的Twikoo评论区或者Email我。

Wtada233's Blog