Skip to content
Back to search

cjk-font-subset

SkillWorks with Claude CodeGitHub

把项目里会显示的汉字抽出来,从源字体生成极小的 woff2(16.9MB → 275KB),并给出能挂 CI 的缺字检查(按字体 cmap 实测、报文件:行号)。支持 file / css 内联 / 回写 fonts.js 三种落地。

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/yi199--cjk-font-subset/badge.svg)](/listings/yi199--cjk-font-subset)

HTML

<a href="/listings/yi199--cjk-font-subset"><img src="/api/listings/yi199--cjk-font-subset/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

# Two dependencies: fonttools reads/writes fonts, brotli handles woff2
python -m pip install fonttools brotli

# Offline self-test: builds a tiny synthetic TTF, no system fonts or network needed
python scripts/selftest.py          # expect: ALL PASS

# Preview missing glyphs without writing anything
python scripts/subset_cjk.py ./app --src <path-to-source-font.ttf> --dry-run

# Emit a woff2 file (H5 / Electron)
python scripts/subset_cjk.py ./app --src <path-to-source-font.ttf> --mode file

# Emit a self-contained @font-face CSS with base64
python scripts/subset_cjk.py ./app --src <path-to-source-font.ttf> --mode css --family MyCJK

# Update an existing fonts.js in place (var ZH = 'data:font/woff2;base64,…')
python scripts/subset_cjk.py ./app --src <path-to-source-font.ttf> \
    --mode inject --target app/data/fonts.js --var ZH

# The authoritative "will anything render as tofu?" check
python scripts/check_cmap.py ./app --fonts app/data/fonts.js --var ZH

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 115 lines
  1. ---
  2. name: cjk-font-subset
  3. slug: cjk-font-subset
  4. version: 1.0.0
  5. displayName: 中文字体子集化 + 缺字校验
  6. description: 把项目里会显示的汉字抽出来,从源字体生成极小的 woff2(16.9MB → 275KB),并给出能挂 CI 的缺字检查(按字体 cmap 实测、报文件:行号)。支持 file / css 内联 / 回写 fonts.js 三种落地。
  7. tags: 中文字体,字体子集,woff2,fonttools,@font-face,base64,缺字检查,小程序,H5,体积优化
  8. license: MIT
  9. ---
  10. # 中文字体子集化 + 缺字校验
  11. 中文字体动辄 10–20 MB,不可能整份发到前端。业界标准做法是**子集化**:只把项目里真正用到的
  12. 汉字切出来,其余丢掉。一个 995 个汉字的项目实测:
  13. ```
  14. Noto Sans SC 可变字体全量 16.9 MB → 子集 woff2 275 KB(base64 内联后约 367 KB)
  15. ```
  16. 体积降 98%,而且不再依赖任何 CDN(内联在包里,无外链、无跨域、无隐私风险)。
  17. 但**光有子集化会翻车**:改了一句文案、灌进一张表格的中文、甚至写了一句中文注释,
  18. 都可能引入字表里没有的字 —— 线上表现是**一小部分字显示成方框**,很难自查。
  19. 所以这套东西必须是两件套:**重建(subset)+ 实测检查(check)**,检查能挂 CI。
  20. ## 什么时候用
  21. - 前端项目里要放中文字体(小程序 / H5 / Electron / PWA / 单页内联)
  22. - 改完中文文案后要确认「没有字变成方框」
  23. - 想把「缺字」变成 CI 上的一条红/绿,而不是上线后靠人眼发现
  24. - 项目里已经有一份 `var ZH = 'data:font/woff2;base64,…'`,改文案后需要原地更新
  25. ## 30 秒上手
  26. ```bash
  27. # 依赖(只这两个:fonttools 读/写字体,brotli 读写 woff2)
  28. python3.12 -m pip install fonttools brotli
  29. # 0) 先自测:不需要任何系统字体、不联网,造一个只含几个汉字的测试字体跑全链路
  30. python3.12 scripts/selftest.py # 期望最后打印 ALL PASS
  31. # 1) 只看缺多少字,不写文件
  32. python3.12 scripts/subset_cjk.py ./app --src C:/Windows/Fonts/NotoSansSC-VF.ttf --dry-run
  33. # 2) 出 woff2 文件(H5 / Electron)
  34. python3.12 scripts/subset_cjk.py ./app --src <源字体> --mode file
  35. # 3) 出 @font-face + base64 的 CSS(单文件自包含)
  36. python3.12 scripts/subset_cjk.py ./app --src <源字体> --mode css --family MyCJK
  37. # 4) 回写项目已有的 fonts.js
  38. python3.12 scripts/subset_cjk.py ./app --src <源字体> --mode inject \
  39. --target app/data/fonts.js --var ZH
  40. # 5) 复验(另一个脚本,口径更严格)—— 这一步才是「有没有方框」的判据
  41. python3.12 scripts/check_cmap.py ./app --fonts app/data/fonts.js --var ZH
  42. ```
  43. `check_cmap.py` 的退出码:**0 = 没有缺字,1 = 有缺字**(可直接挂进 CI / pre-commit)。
  44. ## 为什么是两个脚本、两套口径
  45. | 脚本 | 口径 | 为什么这么定 |
  46. |---|---|---|
  47. | `subset_cjk.py` | **重建口径**:只跳过「整行」`//` 与块注释;行尾注释里的中文**照样进字表** | 重建要**宁可多带字**,少一个大不了多几 KB,少一个就是线上方框 |
  48. | `check_cmap.py` | **严格口径**:`//` 与 `/* */` 全去(保留字符串字面量里的中文,别把 `'https://…'` 截断) | 检查要**宁可报严**,误报只是让你多看一眼,漏报就是事故 |
  49. ⚠️ **只比数量一定漏**。最常见的假绿灯是「代码用到 871 个汉字 / 字表 878 个 ✓ 没有缺字」——
  50. 数量够 ≠ 字够。真实翻车:数量检查全过,真机仍有 7 个字是方框(全部来自刚合进来的两个新页面)。
  51. 唯一可靠判据是 `check_cmap.py` 那样**按字体 cmap 逐字比对**。
  52. ## 六个坑(都踩过)
  53. | # | 坑 | 说明 |
  54. |---|---|---|
  55. | 1 | **行尾注释照样进字表** | 「改注释不必重做子集」只对**独占一行**的注释成立。在两行代码后补一句 `// … 不显示重量栏`,`栏`/`省` 立刻被报缺字。新注释写成独立一行,或避开生僻字 |
  56. | 2 | **测试断言里的中文也算字** | `ok('… 精简 / 命中 / 齐')` 这种断言文案会被算进字表。改断言时顺手避开表外的字(`精简`→`现在`)比为了三个字重建子集划算。但**UI 文案缺字必须重建**,不能靠换字糊过去 |
  57. | 3 | **灌入外部表格数据 = 改文案** | 把动作库表的肌群/器材列灌进详情页,`股四头肌 / 肱二头肌 / 腘绳肌 / 菱形肌 / 药球` 一次报缺 15 字。数据文件单独一份,别为了展示字段改主字典结构 |
  58. | 4 | **顺序铁律:字体 PR 最后合** | 字体子集是全局生成物,依赖**全部**文案。所有改文案的 PR 合完之后,最后单独合字体 PR。否则每合一个就要重建一次(实测:先合字体修 7 字,再合 storage 又带进 3 字,白做一轮) |
  59. | 5 | **`fonts.js` 是生成物,别手改** | 它是一次 base64 几十万字符的单行;手改几乎必然弄坏。要改就重跑;判断缺字是不是你引入的:`git stash -q && <check> ; git stash pop -q`,改前就红说明是前人留下的 |
  60. | 6 | **小程序不能引外部字体文件** | `@font-face` 的 `src` 只认 `https://`(合法域名白名单)或 base64。离线可用 + 不依赖 CDN 就得内联;内联后体积 ≈ woff2 × 4/3(base64 编码膨胀),275 KB 的 woff2 内联后约 367 KB |
  61. ## 源字体怎么选
  62. - **Noto Sans SC / 思源黑体**:SIL OFL 1.1,可商用、可再分发(最常见的选择)
  63. - **可变字体 vs 静态字重**:可变字体(`-VF`)一份含多个字重,`--src` 指它就行;子集化会自动保留用到的轴
  64. - 别用来路不明的「免费字体」:license 不清的字体装进商业项目,是真实的法律风险
  65. - 检查本机有没有 Noto Sans SC:`python3.12 -c "import os;print(os.path.exists('C:/Windows/Fonts/NotoSansSC-VF.ttf'))"`;
  66. 没有就去 Google Fonts 或 `github.com/notofonts/noto-cjk` 取
  67. ## 字号体系(附赠:子集化之后最容易犯的错)
  68. 子集化只解决「字有没有」,不解决「看得清不清」。真实用户反馈「字太小」时的正确做法:
  69. - **字号只从一套 token 来**(如 `--fs-1 … --fs-8` 八档),页面里不写裸 `font-size: 26rpx`
  70. - **中文正文字号有下限**:移动端正文不小于 `32rpx`(约 16px @375 宽),说明文字不小于 `24rpx`
  71. - **调大字号后必须检查卡片标题折行**:字号 +1 档常常让「动作名 + 单位」这一行挤成两行,卡片高度跳变
  72. - 调完拿真机最小屏(如 375×667)过一遍:宽屏好看不算好看
  73. 细节清单见 `references/cjk-font-ops.md`。
  74. ## 文件
  75. - `scripts/subset_cjk.py` —— 抽字 + 子集化 + 三种落地(file / css / inject)
  76. - `scripts/check_cmap.py` —— 严格口径缺字检查,`exit 1` 可直接挂 CI
  77. - `scripts/make_test_font.py` —— 造一个只含指定汉字的极小 TTF(离线自测用)
  78. - `scripts/selftest.py` —— 端到端自测,15 项断言,含「检查器必须真的会红」的反证
  79. - `references/cjk-font-ops.md` —— 口径细节、真实翻车记录、CI 接法、字号体系
  80. ## 边界
  81. - 只处理**汉字/中日韩统一表意文字**(含扩展 A、兼容区)。日文假名、韩文不在此列
  82. - 不管字体设计(字重搭配、行高、字间距),只管「有没有这个字 + 体积」
  83. - `check_cmap.py` 靠扩展名判定,动态拼接出来的中文(如 `'第' + n + '组'`)只能认出字面量部分——
  84. 拼接出来的字要么加进 `--no-safety` 之外的保险字表,要么写个断言把可能值列出来
README.md · README · 78 lines
  1. # cjk-font-subset
  2. **Subset huge CJK fonts down to a tiny woff2, and CI-check that no glyph is missing.** An Agent Skill (SKILL.md) with portable, dependency-light Python scripts for WeChat Mini Programs, H5, Electron, PWA and any web project that ships Chinese text.
  3. A real project using 995 Chinese characters:
  4. ```
  5. Noto Sans SC variable font (full) 16.9 MB
  6. └─ subsetted woff2 275 KB (≈ 367 KB after base64 inlining)
  7. ```
  8. **~98% smaller**, self-contained in the bundle — no CDN, no external font request, no cross-origin or privacy dependency.
  9. ## Why subsetting alone is not enough
  10. Subsetting keeps only the glyphs your project actually uses. But every copy change, imported spreadsheet column, or even a Chinese code comment can introduce a character the subset does not contain — which renders as a hollow box (tofu) in production and is easy to miss in review.
  11. So this skill ships **two tools with intentionally different strictness**:
  12. | Script | Role | Strictness |
  13. |---|---|---|
  14. | `subset_cjk.py` | Rebuild the subset; supports `file` / `css` / `inject` output | Lenient — trailing comments still contribute glyphs, better to carry a few extra than miss one |
  15. | `check_cmap.py` | Verify every used glyph exists in the font's cmap; reports `file:line` | Strict — strips all comments; false positives only cost a glance, a miss is an incident |
  16. `check_cmap.py` exits `0` when complete and `1` on any missing glyph, so it plugs straight into CI / pre-commit. Counting glyphs is **not** a valid check ("871 used / 878 in font ✓" can still show 7 tofu boxes) — only cmap-level per-character comparison is reliable.
  17. ## Quick start
  18. ```bash
  19. # Two dependencies: fonttools reads/writes fonts, brotli handles woff2
  20. python -m pip install fonttools brotli
  21. # Offline self-test: builds a tiny synthetic TTF, no system fonts or network needed
  22. python scripts/selftest.py # expect: ALL PASS
  23. # Preview missing glyphs without writing anything
  24. python scripts/subset_cjk.py ./app --src <path-to-source-font.ttf> --dry-run
  25. # Emit a woff2 file (H5 / Electron)
  26. python scripts/subset_cjk.py ./app --src <path-to-source-font.ttf> --mode file
  27. # Emit a self-contained @font-face CSS with base64
  28. python scripts/subset_cjk.py ./app --src <path-to-source-font.ttf> --mode css --family MyCJK
  29. # Update an existing fonts.js in place (var ZH = 'data:font/woff2;base64,…')
  30. python scripts/subset_cjk.py ./app --src <path-to-source-font.ttf> \
  31. --mode inject --target app/data/fonts.js --var ZH
  32. # The authoritative "will anything render as tofu?" check
  33. python scripts/check_cmap.py ./app --fonts app/data/fonts.js --var ZH
  34. ```
  35. ## Source fonts
  36. - **Noto Sans SC / Source Han Sans** (SIL OFL 1.1) — free for commercial use and redistribution, the common default.
  37. - Variable fonts are supported: point `--src` at the `-VF` file and used axes are preserved automatically.
  38. - Never bundle a "free font" with an unclear license into a commercial product.
  39. ## Scope and limits
  40. - Handles **Han / CJK Unified Ideographs** only (including Extension A and compatibility blocks). Kana and Hangul are out of scope.
  41. - Covers glyph coverage and size, not type design (weight pairing, line height, letter spacing).
  42. - `check_cmap.py` recognizes string literals; dynamically concatenated Chinese (e.g. `'第' + n + '组'`) can only be caught for the literal parts — enumerate possible values in an assertion or an explicit safety glyph list.
  43. ## Repository layout
  44. ```
  45. SKILL.md Agent Skill definition (Chinese; the skill body loaded by AI agents)
  46. scripts/subset_cjk.py Extract glyphs + subset, three output modes
  47. scripts/check_cmap.py Strict missing-glyph check, CI-friendly exit codes
  48. scripts/make_test_font.py Build a minimal TTF for offline testing
  49. scripts/selftest.py End-to-end self-test (15 assertions, incl. negative cases)
  50. references/cjk-font-ops.md Operational details, real failure log, CI wiring, type-scale guidance
  51. ```
  52. ## License
  53. MIT — see [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.