Font Maker CLI

一个高性能、跨平台的命令行工具，用于将 TrueType (.ttf) 和 OpenType (.otf) 字体转换为 MapLibre GL/Mapbox GL 兼容的字形 PBF（Protocol Buffer）格式。

特性

• 🚀 高性能：使用 Worker 线程并行处理
• 🌍 跨平台：支持 Windows、macOS 和 Linux
• 📦 批量处理：同时转换多个字体
• 🎯 多类输出：支持目录结构或压缩包导出
• 💡 字体信息：转换前查看字体元数据

安装

前置要求

• Node.js >= 18.0.0
• npm 或 yarn

本地安装

npm install
npm run build

全局安装

npm install -g .

使用方法

转换字体

将一个或多个字体文件转换为字形 PBF 格式：

# 转换单个字体
font-maker convert path/to/font.ttf

# 转换多个字体
font-maker convert font1.ttf font2.otf font3.ttf

# 指定输出目录
font-maker convert font.ttf -o ./output

# 使用更多并行任务
font-maker convert font.ttf -j 8

# 导出为 ZIP 文件
font-maker convert font.ttf -f zip

# 详细输出
font-maker convert font.ttf -v

选项

• -o, --output <dir>：输出目录（默认：./output）
• -j, --jobs <number>：并行任务数（默认：CPU 核心数）
• -v, --verbose：详细输出
• -f, --format <type>：输出格式：dir（默认）或 zip

字体信息

显示字体文件的信息：

font-maker info path/to/font.ttf

这将显示：

• 字体名称和家族
• 字体样式
• 字形数量
• 字体格式（TrueType、OpenType 等）

输出格式

该工具生成 PBF 格式的字形范围，与 MapLibre GL 和 Mapbox GL 兼容：

output/
├── FontName/
│   ├── 0-255.pbf
│   ├── 256-511.pbf
│   ├── 512-767.pbf
│   └── ... (最多到 65280-65535.pbf)

每个 PBF 文件包含 256 个字符的 Unicode 范围的字形。

性能

CLI 工具针对性能进行了优化：

• 并行处理：默认利用所有 CPU 核心
• Worker 线程：使用 Node.js workers 进行高效的多线程处理
• 内存高效：流式处理数据以避免内存膨胀
• WASM 加速：使用 WebAssembly 进行字体渲染

基准测试

典型转换时间（现代硬件）：

| 字体大小 | 单个字体 | 10 个字体（并行） | |---------|---------|------------------| | 小型 (< 1MB) | ~2-3秒 | ~5-7秒 | | 中型 (1-5MB) | ~5-8秒 | ~12-18秒 | | 大型 (> 5MB) | ~10-15秒 | ~25-35秒 |

与 MapLibre GL 集成

转换后，在你的 MapLibre GL 应用中使用字体：

const map = new maplibregl.Map({
  container: 'map',
  style: {
    version: 8,
    glyphs: 'http://localhost:8080/fonts/{fontstack}/{range}.pbf',
    sources: { /* ... */ },
    layers: [
      {
        id: 'labels',
        type: 'symbol',
        layout: {
          'text-field': '{name}',
          'text-font': ['YourFontName']
        }
      }
    ]
  }
});

示例

将多个字体转换为 ZIP

font-maker convert \
  fonts/Roboto-Regular.ttf \
  fonts/Roboto-Bold.ttf \
  fonts/OpenSans-Regular.ttf \
  -o ./glyphs \
  -f zip \
  -v

使用最大并行度批量处理

font-maker convert fonts/*.ttf -j 16 -o ./output

转换前检查字体

# 首先检查字体信息
font-maker info fonts/MyFont.ttf

# 如果没问题就转换
font-maker convert fonts/MyFont.ttf

架构

┌─────────────┐
│  CLI 入口   │
└──────┬──────┘
       │
       v
┌─────────────────┐
│  字体转换器      │
└──────┬──────────┘
       │
       v
┌─────────────────────────────┐
│   Worker 线程池             │
│  ┌──────┐ ┌──────┐ ┌──────┐│
│  │Worker│ │Worker│ │Worker││
│  │  1   │ │  2   │ │  N   ││
│  └──┬───┘ └──┬───┘ └──┬───┘│
└─────┼────────┼────────┼─────┘
      │        │        │
      v        v        v
┌─────────────────────────────┐
│    WASM 字体处理器           │
│   (sdfglyph + FreeType)     │
└─────────────────────────────┘

故障排除

"找不到模块 @rollup/rollup-win32-x64-msvc"

如果在安装过程中遇到此错误：

rm -rf node_modules package-lock.json
npm install --legacy-peer-deps

WASM 模块加载失败

确保 sdfglyph.wasm 文件存在于 app/public 目录中：

ls -la ../app/public/sdfglyph.wasm

如果缺失，重新构建 WASM 模块：

cd ..
./build_wasm.sh

内存不足

对于非常大的字体或大量并行任务：

# 减少并行任务数
font-maker convert large-font.ttf -j 2

# 或者增加 Node.js 内存
NODE_OPTIONS="--max-old-space-size=4096" font-maker convert large-font.ttf

开发

项目结构

cli/
├── src/
│   ├── index.ts          # CLI 入口点
│   ├── converter.ts      # 字体转换逻辑
│   ├── worker.ts         # Worker 线程实现
│   ├── wasmLoader.ts     # WASM 模块加载器
│   ├── writer.ts         # 输出文件写入器
│   └── fontInfo.ts       # 字体元数据读取器
├── dist/                 # 编译后的 JavaScript（生成）
├── package.json
├── tsconfig.json
└── README.md

构建

npm run build

开发模式运行

npm run dev -- convert font.ttf

相关项目

• MapLibre GL JS
• Font Maker Web 应用 - 基于浏览器的版本
• node-fontnik - 替代字体转换器