Wtada233's Blog

I guarantee this is the most useful tutorial I’ve made—it’s dummy-proof. If you don’t understand, check GitHub.#

Chinese fonts are usually massive (several MBs), and using them directly on a webpage leads to slow loading and a poor user experience. This article introduces how to use Font-Spider to subset and compress Chinese fonts, keeping only the characters actually used on your site, reducing the size to just a few dozen KB.

Preparation: Understanding Font-Spider#

Font-Spider hasn’t been updated in a while, so ignoring pnpm warnings about outdated dependencies is fine.

This tool scans specified files/folders (usually HTML), extracts @font-face tags from CSS, identifies the font, and based on the usage scope, extracts all characters and repacks the font.

The main issue is: what about web paths?

For example, I need to specify the font path as /MiSans-Regular.ttf so all pages can find it, but Font-Spider doesn’t recognize this and tries to find the font at the system root.

In this case, we need the --map parameter. The format is --map "original_path,replacement_path", such as --map "/foobar.ttf,dist/foobar.ttf". This solves the problem.

Step 1: Prepare Font Files#

First, prepare your font file (.ttf format). To make it accessible after Astro builds the site, put it in the public directory.

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

Then, create src/configs/font.ts to manage font configuration:

1
export const fontConfig = {
2
    enable: true,
3
    fonts: [
4
        {
5
            name: "MiSans-Regular",
6
            src: "/MiSans-Regular.ttf",
7
            type: "truetype",
8
            weight: "normal",
9
            style: "normal",
10
            display: "swap",
11
        },
12
    ],
13
    family: "'MiSans-Regular', sans-serif",
14
};

Step 2: Add Font-Spider Dependency#

Install font-spider as a dev dependency:

1
pnpm add -D font-spider

Step 3: Configure Global Styles (Critical)#

For Font-Spider to recognize font usage, you must explicitly declare @font-face and apply font-family.

In Astro, use <style is:global> in your layout file (e.g., src/layouts/Layout.astro). The is:global attribute ensures the style applies to the body and can be crawled by Font-Spider.

1
<style is:global set:html={`
2
${fontConfig.enable ? fontConfig.fonts.map((font) => `
3
    @font-face {
4
        font-family: '${font.name}';
5
        src: url('${font.src}') format('${font.type}');
6
        font-weight: ${font.weight};
7
        font-style: ${font.style};
8
        font-display: ${font.display};
9
    }
10
`).join('') : ''}
11
    body {
12
        font-family: ${fontConfig.family};
13
    }
14
`}></style>

Step 4: Write Automation Script#

Create scripts/compress-font.js to automatically run Font-Spider after building:

(Refer to the original post for the full script content).

Finally, update package.json:

1
"scripts": {
2
  "build": "astro build && node scripts/compress-font.js"
3
}

Now, every time you run pnpm build, your fonts will be automatically optimized!