博客更换中文字体：自托管与子集化

sudo apt-get update
sudo apt-get install -y python3-fonttools python3-brotli curl

cd /path/to/kit
mkdir -p static/fonts

mkdir -p /tmp/blog-font-source

# Regular 对应 CSS 的 400
curl --fail --location --retry 3 \
  --output /tmp/blog-font-source/NotoSerifSC-Regular.otf \
  "https://raw.githubusercontent.com/notofonts/noto-cjk/main/Serif/SubsetOTF/SC/NotoSerifSC-Regular.otf"

# Bold 对应 CSS 的 700
curl --fail --location --retry 3 \
  --output /tmp/blog-font-source/NotoSerifSC-Bold.otf \
  "https://raw.githubusercontent.com/notofonts/noto-cjk/main/Serif/SubsetOTF/SC/NotoSerifSC-Bold.otf"

python3 - <<'PY'
from pathlib import Path

# 当前命令在网站项目根目录执行
project_root = Path.cwd()
output_file = project_root / "static/fonts/charset.txt"

# 这些目录中的内容最终会出现在网页上
scan_dirs = ["src", "templates", "pages", "static"]

# 只读取明确属于文本的文件，避免误读图片、字体和压缩包
text_suffixes = {
    ".md", ".html", ".htm", ".css", ".js", ".json",
    ".svg", ".txt", ".xml", ".yaml", ".yml",
}

characters = set()

for directory_name in scan_dirs:
    directory = project_root / directory_name
    if not directory.exists():
        continue

    for file_path in directory.rglob("*"):
        if not file_path.is_file() or file_path.suffix.lower() not in text_suffixes:
            continue

        # 不读取旧字体的字符基线和许可文件，否则已删除的字符会一直残留
        if output_file.parent in file_path.parents:
            continue

        try:
            characters.update(file_path.read_text(encoding="utf-8"))
        except UnicodeDecodeError:
            print(f"跳过非 UTF-8 文件：{file_path}")

# 英文字母、数字、半角标点和空格
characters.update(chr(code) for code in range(32, 127))

# 给以后常用的中文标点留一点余量
characters.update("，。、；：？！「」『』（）《》〈〉——……·“”‘’【】〔〕～￥×")

# 换行、制表符等控制字符不需要进入字体
characters = {char for char in characters if char.isprintable()}

output_file.parent.mkdir(parents=True, exist_ok=True)
output_file.write_text("".join(sorted(characters)), encoding="utf-8")
print(f"已写入 {output_file}，共 {len(characters)} 个不同字符")
PY

# 正文字体：Regular → 400
python3 -m fontTools.subset \
  /tmp/blog-font-source/NotoSerifSC-Regular.otf \
  --text-file=static/fonts/charset.txt \
  --flavor=woff2 \
  --layout-features='*' \
  --output-file=static/fonts/NotoSerifSC-400.woff2

# 粗体字体：Bold → 700
python3 -m fontTools.subset \
  /tmp/blog-font-source/NotoSerifSC-Bold.otf \
  --text-file=static/fonts/charset.txt \
  --flavor=woff2 \
  --layout-features='*' \
  --output-file=static/fonts/NotoSerifSC-700.woff2

ls -lh static/fonts/*.woff2

@font-face {
  font-family: "Noto Serif SC Selfhost";
  font-style: normal;
  font-weight: 400;
  font-display: optional;
  src: url("fonts/NotoSerifSC-400.woff2") format("woff2");
}

@font-face {
  font-family: "Noto Serif SC Selfhost";
  font-style: normal;
  font-weight: 700;
  font-display: optional;
  src: url("fonts/NotoSerifSC-700.woff2") format("woff2");
}

body {
  /* 英文和数字先用 Georgia，汉字再落到自托管的 Noto Serif SC */
  font-family: Georgia, "Iowan Old Style", "Noto Serif SC Selfhost",
    "Songti SC", SimSun, serif;
}

src: url("fonts/NotoSerifSC-400.woff2?v=20260808") format("woff2");

#!/usr/bin/env bash
set -Eeuo pipefail

# 脚本位于 tools/，因此上一级目录就是网站项目根目录
PROJECT_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
FONT_DIR="${PROJECT_ROOT}/static/fonts"
CHARSET_FILE="${FONT_DIR}/charset.txt"
WORK_DIR="${TMPDIR:-/tmp}/blog-font-source"

# 每项格式：源文件标签|CSS 字重|下载地址
# 换字体时，主要修改这里以及下方的输出文件名前缀
FONT_SOURCES=(
  "Regular|400|https://raw.githubusercontent.com/notofonts/noto-cjk/main/Serif/SubsetOTF/SC/NotoSerifSC-Regular.otf"
  "Bold|700|https://raw.githubusercontent.com/notofonts/noto-cjk/main/Serif/SubsetOTF/SC/NotoSerifSC-Bold.otf"
)

for command_name in python3 curl; do
  if ! command -v "${command_name}" >/dev/null 2>&1; then
    echo "缺少命令：${command_name}"
    echo "Debian/Ubuntu/WSL 可执行：sudo apt-get install python3-fonttools python3-brotli curl"
    exit 1
  fi
done

# 单独检查 Python 模块，报错比运行到一半再失败更容易看懂
if ! python3 -c 'import fontTools.subset, brotli' >/dev/null 2>&1; then
  echo "缺少 fonttools 或 brotli，请执行："
  echo "sudo apt-get install python3-fonttools python3-brotli"
  exit 1
fi

mkdir -p "${FONT_DIR}" "${WORK_DIR}"

echo "1/4 下载字体源文件"
for source_item in "${FONT_SOURCES[@]}"; do
  IFS='|' read -r source_name css_weight source_url <<<"${source_item}"
  source_file="${WORK_DIR}/NotoSerifSC-${source_name}.otf"

  # 已下载的源文件直接复用；需要强制更新时删除 WORK_DIR 后再运行
  if [[ ! -s "${source_file}" ]]; then
    echo "下载 ${source_name}（CSS ${css_weight}）"
    curl --fail --location --retry 3 \
      --output "${source_file}" \
      "${source_url}"
  else
    echo "复用 ${source_file}"
  fi
done

echo "2/4 提取网站字符"
python3 - "${PROJECT_ROOT}" "${CHARSET_FILE}" <<'PY'
import sys
from pathlib import Path

project_root = Path(sys.argv[1])
output_file = Path(sys.argv[2])
scan_dirs = ["src", "templates", "pages", "static"]
text_suffixes = {
    ".md", ".html", ".htm", ".css", ".js", ".json",
    ".svg", ".txt", ".xml", ".yaml", ".yml",
}
characters = set()

for directory_name in scan_dirs:
    directory = project_root / directory_name
    if not directory.exists():
        continue

    for file_path in directory.rglob("*"):
        if not file_path.is_file() or file_path.suffix.lower() not in text_suffixes:
            continue
        if output_file.parent in file_path.parents:
            continue

        try:
            characters.update(file_path.read_text(encoding="utf-8"))
        except UnicodeDecodeError:
            print(f"跳过非 UTF-8 文件：{file_path}")

characters.update(chr(code) for code in range(32, 127))
characters.update("，。、；：？！「」『』（）《》〈〉——……·“”‘’【】〔〕～￥×")
characters = {char for char in characters if char.isprintable()}

output_file.write_text("".join(sorted(characters)), encoding="utf-8")
print(f"字符表：{output_file}")
print(f"字符数：{len(characters)}")
PY

echo "3/4 生成 woff2 子集"
for source_item in "${FONT_SOURCES[@]}"; do
  IFS='|' read -r source_name css_weight source_url <<<"${source_item}"
  source_file="${WORK_DIR}/NotoSerifSC-${source_name}.otf"
  output_file="${FONT_DIR}/NotoSerifSC-${css_weight}.woff2"
  temporary_file="${output_file}.tmp"

  python3 -m fontTools.subset "${source_file}" \
    --text-file="${CHARSET_FILE}" \
    --flavor=woff2 \
    --layout-features='*' \
    --output-file="${temporary_file}"

  # 生成成功后再替换旧文件，避免中途失败留下半个字体
  mv "${temporary_file}" "${output_file}"
  echo "已生成 ${output_file}"
done

echo "4/4 保存字体许可"
curl --fail --location --retry 3 \
  --output "${FONT_DIR}/LICENSE.txt" \
  "https://raw.githubusercontent.com/notofonts/noto-cjk/main/LICENSE"

echo "完成，生成文件如下："
ls -lh "${FONT_DIR}"/*.woff2 "${CHARSET_FILE}" "${FONT_DIR}/LICENSE.txt"

chmod +x tools/subset-fonts.sh
tools/subset-fonts.sh