84 lines
3.4 KiB
Markdown
84 lines
3.4 KiB
Markdown
# 内置字体包集合构建
|
||
|
||
本目录保存字体包配方、许可证、来源说明和正式冻结字体资产。字体二进制
|
||
位于固定的 `font-packs/assets/`，统一由 Git LFS 管理，普通 Git 对象只保存
|
||
LFS 指针。Desktop 安装版、便携版和 Docker 镜像都直接包含本次受校验的
|
||
完整字体包集合，不再依赖用户另行安装字体附件。
|
||
|
||
## 源目录
|
||
|
||
正式发布字体必须先完成许可证、来源、内部字族名、嵌入权限和哈希审查，
|
||
随后固定存放在以下版本化仓库目录：
|
||
|
||
```text
|
||
font-packs/assets/mdtp-serif-sc/1.0.0/
|
||
├── MdTPSerifSC-Regular.ttf
|
||
├── MdTPSerifSC-Regular.woff2
|
||
├── MdTPSerifSC-Bold.ttf
|
||
└── MdTPSerifSC-Bold.woff2
|
||
|
||
font-packs/assets/mdtp-sans-sc/1.0.0/
|
||
├── MdTPSansSC-Regular.ttf
|
||
├── MdTPSansSC-Regular.woff2
|
||
├── MdTPSansSC-Bold.ttf
|
||
└── MdTPSansSC-Bold.woff2
|
||
```
|
||
|
||
该目录中的 `ttf/otf/woff/woff2` 由 `.gitattributes` 强制使用 Git LFS。
|
||
构建器不会联网下载或自动替换字体。派生字体通过
|
||
`font-packs/scripts/build-noto-static.py` 从来源说明固定的 Noto CJK
|
||
可变字体生成；每个发行输入文件都必须与配方声明的
|
||
字节数和 SHA-256 完全一致；TTF 还必须是无需运行时规范化的原生静态
|
||
TrueType，并具有可安装或可编辑的文档嵌入权限。
|
||
|
||
## 构建与验证
|
||
|
||
```powershell
|
||
npm run build:font-pack
|
||
npm run verify:font-pack
|
||
```
|
||
|
||
克隆仓库后应先执行 `git lfs pull`。缺少 LFS 内容时，字体构建会因文件大小
|
||
或 SHA-256 不匹配而拒绝继续，不允许使用系统字体或相近字体静默替代。
|
||
|
||
受版本控制的 `font-packs/bundle.json` 是正式字体包集合清单。构建命令会
|
||
逐包构建、验证，并拒绝 `output/font-packs/root` 中出现清单外字体包，
|
||
避免本地残留进入发行产物。各包报告写入
|
||
`output/font-packs/<pack-id>-build-report.json`。输出布局为：
|
||
|
||
```text
|
||
root/<pack-id>/<semver>/font-pack.json
|
||
```
|
||
|
||
同一 ID 和版本的内容完全相同时，重复构建保持幂等；只要任一文件发生
|
||
变化，构建器就会拒绝覆盖。发行内容变化必须提升字体包 SemVer。
|
||
|
||
当前 `mdtp-serif-sc@1.0.0` 只替换 `FandolSong` 与
|
||
`Mdpdf Fandol Song` 的 400/700 字重，不匹配 `SimSun` 等通用别名，避免
|
||
错误替换仿宋、黑体、楷体或普通外部主题字体。
|
||
|
||
`mdtp-sans-sc@1.0.0` 提供 `MdTP Sans SC`、`FandolHei`、
|
||
`Microsoft YaHei`、`PingFang SC`、`Noto Sans CJK SC` 和
|
||
`Source Han Sans SC` 的 400/700 字重映射。主题仍需明确声明所需字体面，
|
||
注册器不会对未声明字体进行静默替换。
|
||
|
||
## Desktop 内置发行
|
||
|
||
组合构建命令为：
|
||
|
||
```powershell
|
||
npm run desktop:make:with-font-pack
|
||
```
|
||
|
||
该命令先重建完整字体包集合，再构建主安装器和便携 ZIP。electron-builder
|
||
把 `output/font-packs/root` 复制到 `resources/font-packs`；Desktop 生产
|
||
运行时优先读取该只读内置根目录，再读取用户目录中的额外字体包。内置包
|
||
因此不会被缺失、旧版或同 ID 用户包替换。
|
||
|
||
## Docker 内置发行
|
||
|
||
Docker 构建前必须先执行 `npm run build:font-pack`。构建上下文只放行
|
||
`output/font-packs/root`，Dockerfile 将其复制到
|
||
`/app/.local/font-packs`；Compose 不再挂载宿主机字体目录。字体因此随
|
||
镜像离线分发，同时仍由运行时注册器校验版本、路径、容量和 SHA-256。
|