mirror of
https://github.com/2234839/web-font.git
synced 2026-11-23 04:38:45 +08:00
- backend/routes/svg.ts:文字→TrueType 二次贝塞尔轮廓路径 SVG,LRU 缓存+颜色注入防护,供 README/邮件等 <img> 场景展示字体效果(SVG 图片无法引用外部字体,矢量路径是唯一可渲染形态) - rust-spike/src/svg.rs:对译 Rust 版,复用进程级 Font 缓存 cmap_get+glyph_contours(跳过子集化更快),与 TS 版输出字节级一致(cmp 验证) - ttf.rs 新增 Font::advance_width(hmtx spec 继承语义) - README 新增「字体效果预览」章节,6 款字体实时 SVG - v1.16.0 已发布上线,公网 /api/svg 验证 200+缓存 HIT
250 lines
11 KiB
Markdown
250 lines
11 KiB
Markdown
# WebFont — 中文字体按需裁剪 + AI 字体技能
|
||
|
||
> 按需裁剪中文字体,6 个字 ≈ 6KB。让任何网页、海报、H5 都能用上高级中文字体。
|
||
|
||
[English](README.en.md)
|
||
|
||
[](https://tsfullstack.heartstack.space/group/gs?from=web-font)
|
||
|
||
**中文字体包太大**(思源黑体 16MB+),没法像英文字体那样直接 `@font-face` 引入。
|
||
|
||
本项目在服务端按需子集化字体——传什么文字,就只返回那些字符的字体子集。一张海报用了 20 个字?返回的字体文件就是 20KB,而不是 16MB。
|
||
|
||
```html
|
||
<!-- 一段 CSS 即可使用任意中文字体 -->
|
||
<style>
|
||
@font-face {
|
||
font-family: "MyFont";
|
||
src: url("https://webfont.shenzilong.cn/api?font=令东齐伋复刻体&text=静心茶舍&outType=ttf") format("truetype");
|
||
}
|
||
.title { font-family: "MyFont", serif; }
|
||
</style>
|
||
<h1 class="title">静心茶舍</h1>
|
||
```
|
||
|
||
## 谁在用
|
||
|
||
**任何需要中文 Web Font 的场景:**
|
||
|
||
- 海报 / H5 活动页 — 几个字裁剪后只有几 KB
|
||
- 品牌官网 — 高级字体不再受限于体积
|
||
- 小程序 / PWA — 流量敏感,按需加载
|
||
- 静态博客 / CMS — 文字内容确定,CSS 直出即可
|
||
- LeaferJS 画布 / 设计工具 — [leafer-x-webfont](https://www.npmjs.com/package/leafer-x-webfont) 插件,画布 Text 用什么字体就加载那几个字([在线 demo](https://webfont.shenzilong.cn/leafer-demo/))
|
||
- AI 生成网页 — 让 AI 也能输出有设计感的中文字体方案
|
||
|
||
## 字体效果预览
|
||
|
||
下面这些图片不是截图,而是服务端实时返回的 **SVG 矢量文字**(`/api/svg` 接口把字符转成字形轮廓路径,无需加载字体文件即可在任意环境渲染):
|
||
|
||
<p>
|
||
<img src="https://webfont.shenzilong.cn/api/svg?font=%E4%BB%A4%E4%B8%9C%E9%BD%90%E4%BC%8B%E5%A4%8D%E5%88%BB%E4%BD%93.ttf&text=%E9%9D%99%E5%BF%83%E8%8C%B6%E8%88%8D&color=333" alt="令东齐伋复刻体 - 静心茶舍" height="52"><br>
|
||
<sub>令东齐伋复刻体</sub>
|
||
</p>
|
||
<p>
|
||
<img src="https://webfont.shenzilong.cn/api/svg?font=%E5%BE%97%E6%84%8F%E9%BB%91.ttf&text=%E5%BF%AB%E5%A6%82%E9%97%AA%E7%94%B5&color=333" alt="得意黑 - 快如闪电" height="52"><br>
|
||
<sub>得意黑</sub>
|
||
</p>
|
||
<p>
|
||
<img src="https://webfont.shenzilong.cn/api/svg?font=%E9%9C%9E%E9%B9%9C%E6%96%87%E6%A5%B7.ttf&text=%E6%B8%A9%E6%9F%94%E5%B2%81%E6%9C%88&color=333" alt="霞鹜文楷 - 温柔岁月" height="52"><br>
|
||
<sub>霞鹜文楷</sub>
|
||
</p>
|
||
<p>
|
||
<img src="https://webfont.shenzilong.cn/api/svg?font=%E9%A9%AC%E5%85%8B%E7%AC%94%E5%93%A5%E7%89%B9%E4%BD%93.ttf&text=%E6%97%A0%E7%95%8F%E9%80%A0%E6%A2%A6&color=333" alt="马克笔哥特体 - 无畏造梦" height="52"><br>
|
||
<sub>马克笔哥特体</sub>
|
||
</p>
|
||
<p>
|
||
<img src="https://webfont.shenzilong.cn/api/svg?font=%E5%88%98%E5%BB%BA%E6%AF%9B%E8%8D%89.ttf&text=%E4%B9%98%E7%89%A9%E6%B8%B8%E5%BF%83&color=333" alt="刘建毛草 - 乘物游心" height="52"><br>
|
||
<sub>刘建毛草</sub>
|
||
</p>
|
||
<p>
|
||
<img src="https://webfont.shenzilong.cn/api/svg?font=%E4%BC%98%E8%AE%BE%E6%A0%87%E9%A2%98%E9%BB%91.ttf&text=%E5%AD%97%E9%9A%8F%E9%9C%80%E8%BD%BD&color=333" alt="优设标题黑 - 字随需载" height="52"><br>
|
||
<sub>优设标题黑</sub>
|
||
</p>
|
||
|
||
用法(参数:`font` 字体名 / `text` 文字 / `size` 字号 12-400 / `color` 十六进制颜色):
|
||
|
||
```html
|
||
<img src="https://webfont.shenzilong.cn/api/svg?font=得意黑.ttf&text=快如闪电&size=64&color=333333">
|
||
```
|
||
|
||
适合 README 徽章式标题、邮件内嵌图、不支持自定义字体的第三方页面等场景——输出的 SVG 只有几 KB,且矢量无限清晰。
|
||
|
||
## 核心能力
|
||
|
||
> [在线体验中文字体效果对比](https://webfont.shenzilong.cn/?demo) — 同一内容,字体不同,体验天壤之别
|
||
|
||
### Runtime Font Delivery
|
||
|
||
服务端按需子集化 + 客户端增量加载。
|
||
|
||
```
|
||
6 个字 → 服务端裁剪 → 返回约 6KB 子集字体(而非 16MB 完整字体)
|
||
```
|
||
|
||
**裁剪性能**(Node.js 实测,令东齐伋复刻体,50 轮平均值):
|
||
|
||
| 场景 | ttf | woff2 | 输出大小 |
|
||
|------|-----|-------|----------|
|
||
| 拉丁 + 数字(Hello World 123) | **0.11ms** | 0.13ms | 0.4KB |
|
||
| 8 个汉字 | **0.17ms** | 0.38ms | 8KB |
|
||
| 千字文前段(88 字) | **0.37ms** | 2.11ms | 78KB |
|
||
|
||
小字集(常用场景)裁剪已达**亚毫秒级**;耗时随字形数量线性增长,woff2 的额外开销来自 brotli 压缩(原生硬下限)。响应头 `X-Timing-Find/Read/Subset/Total` 可观测各阶段耗时。
|
||
|
||
JS SDK 三种加载模式:
|
||
|
||
```html
|
||
<script src="https://webfont.shenzilong.cn/webfont-sdk.js"></script>
|
||
<script>
|
||
// 推荐:MutationObserver 事件驱动,DOM 变化自动加载新字符
|
||
WebFont.observeFont({ fontName: "令东齐伋复刻体.ttf", selector: ".content", family: "MySerif" });
|
||
|
||
// 轮询模式
|
||
WebFont.loadFont({ fontName: "令东齐伋复刻体.ttf", selector: ".title", family: "MySerif" });
|
||
|
||
// 手动传入文本
|
||
var loader = WebFont.loadText({ fontName: "令东齐伋复刻体.ttf", text: "你好世界", family: "MySerif" });
|
||
loader.update("追加文字");
|
||
</script>
|
||
```
|
||
|
||
同一字体下所有模式共享字符集,零重复请求,零闪烁。
|
||
|
||
### AI Chinese Font Skill
|
||
|
||
给 AI(Claude、Cursor、Copilot 等)注入中文字体应用能力。AI 读取 Skill Prompt 后可以:
|
||
|
||
- 自动选择匹配场景的中文字体
|
||
- 正确处理中英混排
|
||
- 建立字体层级(Font Hierarchy)
|
||
- 生成 fallback 链和 Runtime 加载策略
|
||
|
||
```
|
||
Prompt: "生成一个东方禅意风格的茶品牌官网"
|
||
|
||
无 Skill: font-family: sans-serif → 系统黑体 → 廉价感
|
||
|
||
有 Skill: zen 风格 → 宋体标题 + 楷体正文 → 自动子集化 → 质感显著提升
|
||
```
|
||
|
||
## 快速开始
|
||
|
||
### 直接调用 API
|
||
|
||
无需 SDK,一段 CSS 即可。服务端只返回你需要的字符子集。
|
||
|
||
```css
|
||
@font-face {
|
||
font-family: "MyFont";
|
||
src: url("https://webfont.shenzilong.cn/api?font=令东齐伋复刻体&text=你的文字&outType=ttf") format("truetype");
|
||
}
|
||
```
|
||
|
||
### 自部署
|
||
|
||
后端有 **三个运行时实现**,行为对齐(API/缓存/并发闸门一致),按需选择:
|
||
|
||
| 运行时 | 产物 | 特点 |
|
||
|--------|------|------|
|
||
| **Rust**(`rust-spike/`,推荐) | musl 静态单二进制(~2.2MB) | 零运行时依赖,`FROM scratch` 镜像仅 ~5MB,端到端亚毫秒级裁剪 |
|
||
| Node.js(`backend/`) | `dist_backend/app.cjs` | 开发调试方便,`tsx` 直跑源码热更 |
|
||
| LLRT | `dist_backend/app.lrt` | AWS 轻量运行时,冷启动快,适合 Lambda 形态 |
|
||
|
||
Rust 版为生产主力:每连接一线程并发,内存感知闸门(内存够则真并发裁剪,默认上限 4,不够则排队,超时回 503),字体 API 响应带强缓存 + ETag 协商。
|
||
|
||
```bash
|
||
# Rust(生产推荐;需 rustup target add x86_64-unknown-linux-musl)
|
||
pnpm install && pnpm build && pnpm build_backend_rs
|
||
PORT=8087 FONT_DIRS=./font ./dist_backend/webfont-rs
|
||
|
||
# Node.js(开发)
|
||
pnpm build_backend && node ./dist_backend/app.cjs
|
||
|
||
# LLRT
|
||
pnpm build_backend && ./llrt ./dist_backend/app.cjs
|
||
```
|
||
|
||
Docker(scratch 镜像,仅 ~5MB):
|
||
|
||
```yaml
|
||
services:
|
||
webfont:
|
||
image: docker.io/llej0/web-font:latest
|
||
ports:
|
||
- "8087:8087"
|
||
volumes:
|
||
- ./fonts:/home/font
|
||
environment:
|
||
- ENABLE_TEMP_UPLOAD=true
|
||
- ADMIN_API_KEY=your-secret-key
|
||
- SUBSET_CACHE_MAX_SIZE=10485760
|
||
# 临时字体保留时限(秒),超时未使用自动删除,默认 10800(3小时)
|
||
- TEMP_RETENTION_SECONDS=10800
|
||
# 字体裁剪最大并发数,默认 4(内存受限环境建议 2-3)
|
||
- SUBSET_CONCURRENCY=4
|
||
```
|
||
|
||
## API
|
||
|
||
| 接口 | 说明 |
|
||
|------|------|
|
||
| `GET /api?font={name}&text={chars}&outType={woff2\|ttf}` | 裁剪字体,只返回指定字符的子集 |
|
||
| `GET /api/fonts` | 列出可用字体 |
|
||
| `GET /api/config` | 获取服务配置 |
|
||
| `POST /api/upload?mode=temp` | 临时上传(自动清理) |
|
||
| `POST /api/upload?mode=admin` | 永久上传(需 API Key) |
|
||
|
||
字体名支持模糊匹配:精确 > 前缀 > 包含。
|
||
|
||
## 架构
|
||
|
||
```
|
||
┌──────────────────────────────────────────────────────────────┐
|
||
│ 使用场景 │
|
||
│ 海报/H5 · 品牌官网 · 博客 · 小程序 · AI 生成页面 │
|
||
└──────────────────────────┬───────────────────────────────────┘
|
||
│
|
||
┌────────────┴────────────┐
|
||
│ AI Chinese Font Skill │ ← 中文字体应用能力
|
||
│ + Skill Prompt │ ← 字体裁剪 + 加载策略
|
||
└────────────┬────────────┘
|
||
│
|
||
┌────────────┴────────────┐
|
||
│ Runtime Font Delivery │ ← 按需子集化 + 增量加载
|
||
│ SDK + API │
|
||
└────────────┬────────────┘
|
||
│
|
||
┌────────────┴────────────┐
|
||
│ Subset Engine │ ← fonteditor-core
|
||
│ parse → subset → │ 字体解析、子集化、格式转换
|
||
│ optimize → serialize │
|
||
└─────────────────────────┘
|
||
```
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
web-font/
|
||
├── backend/ # 服务端:HTTP API + 字体裁剪引擎
|
||
│ ├── routes/ # API 路由
|
||
│ ├── font_util/ # 字体裁剪核心
|
||
│ └── server/ # HTTP 服务器(兼容 Node.js + LLRT)
|
||
├── src/ # 前端:Vue 3 单页应用
|
||
├── public/
|
||
│ └── webfont-sdk.js # Runtime Font Delivery SDK
|
||
├── skills/ # AI Chinese Font Skill
|
||
├── examples/ # Before/After 对比演示
|
||
└── vendor/ # fonteditor-core
|
||
```
|
||
|
||
## 鸣谢
|
||
|
||
- [kekee000/fonteditor-core](https://github.com/kekee000/fonteditor-core) — 字体解析、子集化、格式转换
|
||
- [字体天下](http://www.fonts.net.cn/commercial-free-32767/fonts-zh-1.html) — 免费商用中文字体
|
||
- 入选[阮一峰科技爱好者周刊第 100 期](https://www.ruanyifeng.com/blog/2020/03/weekly-issue-100.html)
|
||
|
||
## License
|
||
|
||
MIT © [崮生](https://shenzilong.cn)
|