字体与主题

字体配置

Vergil 支持自定义字体，配置在 src/data/config/fonts.ts 的 fonts 字段中。

默认字体

fonts: {
    display: 'maokenZhuyuanTi',
    body: 'lxgwwenkai',
    ui: 'maokenZhuyuanTi',
    mono: 'monoFonts'
}

添加自定义字体

1. 将字体文件放入 scripts/fonts-source/ 目录
2. 在 src/data/config/fonts.ts 的 fontsRegistry 中注册：

fontsRegistry: {
    myFont: {
        cssName: 'My Font',
        family: 'sans-serif',
        path: '/fonts/my-font.woff2',
        format: 'woff2'
    }
}

3. 在 fonts 配置中引用：

fonts: {
    display: 'myFont',
    body: 'myFont'
}

4. 运行子集化脚本生成优化后的字体文件：

bash scripts/subset-fonts.sh

使用 CDN 字体（免子集化）

如果字体有现成的 CDN 地址（如 Google Fonts、阿里云 CDN），可以直接通过 cdn 字段引用，无需本地文件和子集化：

fontsRegistry: {
    myFont: {
        cssName: 'My Font',
        family: 'sans-serif',
        cdn: 'https://cdn.example.com/fonts/my-font.woff2'
    }
}

使用 cdn 时，字体文件会在页面中通过 @font-face 直接加载，不会经过子集化处理。适合：

• 已经有 CDN 分发的商用字体
• 体积较小的西文字体（如 Google Fonts 的 Inter）
• 不想维护本地字体文件的场景

单篇文章自定义字体

在文章信息头中覆盖字体：

---
title: 特殊排版文章
fonts:
  display: 'maokenZhuyuanTi'
  body: 'lxgwwenkai'
---

主题切换

Vergil 支持暗色/亮色模式切换，点击网站右上角的太阳/月亮图标即可切换。

配色方案

Vergil 提供 11 种配色方案（A-K），在主题切换面板中选择：

• 点击右上角主题图标
• 选择喜欢的配色方案
• 系统会自动保存你的选择

暗色模式

在配色方案旁边有单独的暗色/亮色切换开关，独立于配色方案。

默认主题

如果你想设置网站默认的配色方案和暗色模式，可以在 src/data/site-config.ts 中配置（高级用法）。

---

字体体积优化

中文字体文件通常很大（单文件 5-30MB），直接加载会严重影响首屏速度。Vergil 内置了自动化子集化方案来解决这个问题。

为什么需要子集化

中文字体包含成千上万个字形（矢量图形），但你的网站实际用到的可能只有几百个。子集化就是只保留实际需要的字形，删除没用到的，从而大幅减小文件体积。

双文件加载策略

Vergil 为每种字体生成两个文件：

文件	内容	大小	加载方式
字体名-subset.woff2	全站精确用字 + ASCII	~200-300KB	立即加载（preload）
字体名.woff2	GB2312 一级常用字 + ASCII	~600-900KB	后台加载

加载流程：

1. 首屏先加载 subset 文件（~250KB），页面文字立即渲染
2. 浏览器空闲时加载 full 文件（~800KB），补充缺失字形
3. 遇到二级汉字（生僻字）时，若 full 文件尚未加载完成，会短暂回退到系统字体（苹方/微软雅黑），full 文件加载完成后自动纠正

使用子集化脚本

bash scripts/subset-fonts.sh

脚本会自动完成以下工作：

1. 扫描 src/content/ 和 public/ 提取全站用字
2. 合并 ASCII 字符和 GB2312 一级常用字（3755字）
3. 为 scripts/fonts-source/ 下每个 .ttf 文件生成两个 .woff2
4. 输出到 public/fonts/

添加新字体：

1. 将 .ttf 文件放入 scripts/fonts-source/
2. 在 fontsRegistry 中注册（见上方”添加自定义字体”）
3. 运行 bash scripts/subset-fonts.sh
4. 构建部署

字体文件目录说明

scripts/fonts-source/       ← 字体源文件（.ttf），不入构建产物
├── LXGWWenKai-Regular.ttf
└── maoken-zhuyuan-ti.ttf

public/fonts/               ← 子集化后的文件（.woff2），进入 dist
├── LXGWWenKai-Regular-subset.woff2
├── LXGWWenKai-Regular.woff2
├── maoken-zhuyuan-ti-subset.woff2
└── maoken-zhuyuan-ti.woff2