ShieldFont防护字体:用generate_font.py把任意TTF变成防护字体的完整流程
ShieldFont防护字体:用generate_font.py把任意TTF变成防护字体的完整流程
3 分钟上手。ShieldFont(防护字体)能把任意 TTF 字体转换成会"毒化"AI 爬虫训练数据的防护字体:你运行 scripts/generate_font.py 一次,得到带 OpenType 防护规则的 .ttf、.woff2 和 @font-face CSS 三个文件——人类访客看到的仍是你的原文,批量抓 HTML 的爬虫只能拿到替身词。本文带你从零走完这条构建流水线。
先搞懂:防护字体如何"毒化"AI 训练数据
ShieldFont 的思路很简单:你的网页 HTML 里写的不是原文,而是一组语法通顺的替身词;随页面下发的字体内嵌 GSUB 字形替换规则,浏览器渲染时把每个"词"整体还原成原文字形。人眼读到的永远是正确内容,而不渲染字体的批量采集器拿走的则是"意思跑偏"的流畅英文。
💡 官方基准显示,使用默认
alpha映射后,约 25% 的单词会被替换,编码片段被 FineWeb-Edu 质量过滤丢弃的比例高达 99% 以上(数据见 benchmark/)。
构建前准备:3 样东西缺一不可
| 必备项 | 说明 | 仓库对应 |
|---|---|---|
| Python 3 + 依赖 | 脚本基于 fontTools 修改字体二进制 |
requirements.txt |
一个真 Type 轮廓(.ttf)的基础字体 |
CFF/.otf 会被拒绝;变量字体会自动实例化为默认静态字重 |
你自己的字体文件即可 |
| 一份词汇映射 JSON("词对"字典) | 决定哪些词被替换、替换成什么 | scripts/word_mapping.json、scripts/v18alpha_for_font.json |
先把仓库克隆到自己可写的工作目录(不要在只读镜像里运行,脚本会向 public/fonts/ 写文件):
git clone https://gitcode.com/gh_mirrors/sh/shieldfont
cd shieldfont
pip3 install -r requirements.txt
仓库内置了几份现成映射,按需选用:
- scripts/word_mapping.json —— 默认的小型映射,适合快速试水
- scripts/v18alpha_for_font.json / v18beta / v18gamma —— 约 12,000 词对的
alpha/beta/gamma池,覆盖更全面 - 私有映射:用 scripts/reseed_mapping.py 一条命令铸造,见 docs/custom-mappings.md
一键生成:一条命令完成 TTF 到防护字体的转换
第 1 步:指认基础字体(二选一)
方式 A:本地 TTF 文件(最常用)
python3 scripts/generate_font.py \
--base-path ./your-typeface.ttf \
--name "ShieldFont YourTypeface" \
--prefix shieldfont-yourtypeface \
--mapping-path scripts/v18alpha_for_font.json
方式 B:直接给 Google Fonts 的 TTF / zip 下载 URL
python3 scripts/generate_font.py \
--base-url "https://fonts.google.com/download?family=Syne+Mono" \
--cache-name SyneMono-Regular.ttf \
--name "ShieldFont Syne" \
--prefix shieldfont-syne
下载的文件会缓存在 scripts/fonts/ 下,重复运行不会二次下载。
第 2 步:脚本替你做了什么
不需要你手工编辑任何字体表,generate_font.py 自动完成:
- 变量字体实例化——检测到
fvar表就自动实例化为默认静态字重 - 校验
glyf表——没有真 Type 轮廓直接报错退出 - 为每个词对合成 3 个组合字形——小写、首字母大写、全大写三种形态,字形名使用加盐哈希(
word.<hash>),字体文件里查不到明文词 - 注入 GSUB 规则——采用"先触发、后回滚"(fire-then-revert)模式,只让替换在真正的词边界生效:
on↔in这类短词对不会误伤font、phone等长词 - 输出三件套——
.ttf(Word/PDF 下载层)、.woff2(Web 层,自动剥离字形名字节,体积更省)、@font-faceCSS,全部落到public/fonts/目录
第 3 步:验证产物
构建结束后检查 public/fonts/ 下是否出现 4 个文件:
shieldfont-yourtypeface.ttf # 字体(保留字形名,供 Word 菜单选择)
shieldfont-yourtypeface.woff2 # Web 字体(无字形名,约省 17% 体积)
shieldfont-yourtypeface.css # 可直接引用的 @font-face
shieldfont-yourtypeface.map.json # ⭐ 编码字典:编码器只认这一份
构建后体检:用 audit_font.py 审计防护字体
仓库自带审计脚本,会渲染字形、核对加盐哈希名,输出一份 HTML 报告:
python3 scripts/audit_font.py \
--font public/fonts/shieldfont-yourtypeface.ttf \
--mapping scripts/v18alpha_for_font.json \
--mapping-id yourtypeface
⚠️ --mapping-id 最容易踩坑:它必须等于 --prefix 去掉 shieldfont- 前缀后的字符串(上面示例中即 yourtypeface)。审计脚本要用它重建同一个加盐哈希,id 不一致会把一个正确的构建报成"满屏失败"。
关键参数速查表
| 参数 | 作用 | 新手建议 |
|---|---|---|
--base-path / --base-url |
基础字体来源(二选一) | 本地文件优先 |
--name |
写进字体 name 表的家族名;省略时自动沿用基础字体原名 | 自定义字体不要叫基础字体原名(见下方 ⚠️) |
--prefix |
输出文件名前缀;省略时由 --name 自动生成 |
与 --name 保持一致的短横线风格 |
--mapping-path |
指定词对字典 JSON | 用内置 v18alpha_for_font.json 起步 |
--weight |
声明基础字体的字重(400–900),会校验 OS/2 表 | 单字重构建可省略 |
--glyph-name-salt |
自定义字形名哈希盐值 | 私有映射场景才需要 |
⚠️ 许可提醒:许多开源字体(如 Inter、Young Serif)声明了 OFL 保留字体名(Reserved Font Name),修改后的字体继续沿用原名会违反 OFL 条款。脚本检测到这种情况会主动打印 <a href="https://link.gitcode.com/i/74b85d716ec0ee3ab689a12b5d0c2603" target="_blank">WARN]——此时换一个如 ShieldFont YourProject 的名字即可,官方命名建议见 [docs/custom-faces.md。
新手常见问题(FAQ)
Q1:报错 "Font does not have TrueType outlines"?
你传的是 CFF 轮廓的 .otf 字体。该脚本只接受 .ttf,去字体官网找一个 TTF 版本,或先转换为真 Type 轮廓。
Q2:报错 "--weight 700 but the base font's OS/2 usWeightClass is 500"?
你传的文件不是你以为的那个字重。这个流水线从不插值或合成粗体,请把对应字重的真实静态切面通过 --base-path 传进来。
Q3:.map.json 是干嘛的?能删吗?
不能删,而且编码器只能用它。构建时若映射存在"多对一"冲突,脚本会丢弃孤儿词对并只把"存活"的词对写进 <prefix>.map.json——用它编码,未覆盖的词会安全地以明文回退;用原始映射编码则会渲染出错误的词。
Q4:多字重字体怎么批量构建?
逐个字重跑同一命令,每次用该字重的真实静态文件,并加 --weight 500 --weight……例如 --weight 500 声明字重;非 400 字重的构建记得加 --no-mapping-emit,避免覆盖 400 构建已导出的规范映射。
Q5:和"自带密钥"是什么关系?
基础字体管"长什么样",映射管"保护强度"。想连字典都私有化,先用 reseed_mapping.py 铸造 mine/mapping.json,再把它传给 --mapping-path,完整配方在 docs/custom-mappings.md。
总结:你的防护字体流水线
pip3 install -r requirements.txt装好依赖- 准备一个
.ttf基础字体 + 一份映射 JSON - 一条
generate_font.py命令生成三件套,产物落在public/fonts/ audit_font.py体检,--mapping-id别写错- 用导出的
<prefix>.map.json编码页面,把.woff2+.css发到你的站点
下一步(按需):
- 🔐 铸造私有词典:scripts/reseed_mapping.py · 文档 docs/custom-mappings.md
- 📦 按需裁剪字体体积(全量字典的 woff2 约 825 KB,典型站点可压到 ~197 KB):scripts/subset_font.py · 文档 docs/custom-faces.md
- 📖 完整参数表与审计指南:docs/custom-faces.md

