IBM Plex Mono 字体 Web 集成实战指南:从 npm 安装、SCSS 字重定制到源码构建
IBM Plex Mono 字体 Web 集成实战指南:从 npm 安装、SCSS 字重定制到源码构建
@ibm/plex-mono 是 IBM Plex® 等宽字体系列(IBM Plex Mono)的官方 npm 发行包,为开发者同时提供了可直接使用的 CSS、可深度定制的 Sass(SCSS)模块,以及按 Unicode 子集拆分、面向性能优化的 woff2/woff 字体文件。本指南将完整梳理该包在设备端与 Web 端的安装方式、CSS/SCSS 两种引用路径、字重导入与裁剪策略、@font-face 与 unicode-range 的底层生成原理,以及从 .vfb 源文件构建字体的完整工具链,帮助你在项目中以正确、高效的方式接入 IBM Plex Mono。
包结构与发行内容
packages/plex-mono/ 是 monorepo 中的一个独立子包,其元信息定义在 packages/plex-mono/package.json 中:
- 包名:
@ibm/plex-mono(版本2.5.0) - 许可证:OFL-1.1(SIL Open Font License)
- 发布文件清单(
files字段):css、scss、fonts/complete/woff/*、fonts/complete/woff2/*、fonts/split/woff2/*、telemetry.yml
从 packages/plex-mono/README.md 可知,该包面向 Web 开发的核心资产有三类:
- 拆分后的高性能子集字体:
.woff2与.woff格式,按字重 × 语系子集拆分成多个小文件,浏览器可借助 CSSunicode-range按需下载; - CSS 文件:可直接引用任意字重、变体与子集组合的级联样式表;
- SCSS 模块:提供更细粒度的配置与输出控制,如自定义字体文件路径前缀、按需启用/禁用字重。
包内不包含 .otf/.ttf 等桌面格式,README 明确说明原因是 NPM 包体积限制——npm 包只携带 .woff2 与 .woff。不过完整的桌面字体文件仍然保存在本仓库中,例如 packages/plex-mono/fonts/complete/ttf/IBMPlexMono-Regular.ttf 与 packages/plex-mono/fonts/complete/otf/IBMPlexMono-Regular.otf,以及 complete/woff2/、complete/woff/ 下的完整字重文件,供本地安装或自托管使用。
包内目录速览
packages/plex-mono/
├── fonts/
│ ├── complete/ # 完整字体(每字重单文件)
│ │ ├── otf/ ttf/ woff/ woff2/
│ └── split/ # 按 Unicode 子集拆分(每字重多文件)
│ ├── woff/ woff2/
├── css/ # 编译好的 CSS(随 npm 包发布)
├── scss/ # SCSS 源码模块(随 npm 包发布)
├── package.json
├── telemetry.yml # 遥测配置
└── README.md
split/ 目录下的每个字重都按 Latin1、Latin2、Latin3、Cyrillic、Pi 五个子集拆分,并附带对应的 .css 文件,例如 packages/plex-mono/fonts/split/woff2/IBMPlexMono-Regular-Latin1.woff2 与 packages/plex-mono/fonts/split/woff2/IBMPlexMono-Regular.css。
安装:设备端与 Web 端两条路径
安装到本机设备
如需在操作系统层面安装 IBM Plex Mono(用于 IDE、终端、设计工具等),应从项目发布的 zip 压缩包中获取 .otf/.ttf 文件。本仓库的 packages/plex-mono/fonts/complete/ttf/ 与 packages/plex-mono/fonts/complete/otf/ 已内置 16 个字重变体(8 个正体 × 8 个斜体)的桌面字体文件。
通过 npm 安装到 Web 项目
在 Node.js 环境下,一条命令即可完成安装:
npm install @ibm/plex-mono
安装后,node_modules/@ibm/plex-mono/ 中即包含 css/、scss/ 与 fonts/ 目录,可被构建工具(webpack、Vite、Parcel 等)或 CDN 直接引用。需要说明的是,安装 @ibm/plex-mono 时,postinstall 钩子会运行 ibmtelemetry --config=telemetry.yml,即触发 IBM Telemetry 数据采集(详见后文"IBM Telemetry 说明"一节)。
另一种手动方式是从项目发布包中下载 Web 专用 zip,解压后保持目录结构放入静态资源目录。
Web 使用:CSS 与 SCSS 两种集成方式
方式一:直接使用 CSS 文件
包内预编译好的 CSS 位于 css/ 目录(随 npm 包发布),引用时必须保持原始目录结构,否则 @font-face 中声明的相对路径将无法解析到字体文件。典型做法是把 node_modules/@ibm/plex-mono/ 整个拷贝或映射到你的静态资源目录下,例如:
<link rel="stylesheet" href="/vendor/@ibm/plex-mono/css/plex-mono.css" />
之后即可在样式中使用 font-family: 'IBM Plex Mono';。
方式二:通过 SCSS 模块定制引用
SCSS 方式的核心优势是可以在 @use 时通过配置变量精确控制输出。首先引入模块并设置字体文件路径前缀:
@use '@ibm/plex-mono/scss' as PlexMono with (
$font-prefix: 'font-path'
);
@include PlexMono.all();
$font-prefix用于声明字体文件的实际路径前缀(即@font-face中url(...)的公共前缀),默认值为'..'。当你把字体文件放在与 SCSS 输出不同的目录时,务必通过该变量修正路径,否则浏览器会因 404 而无法加载字体。PlexMono.all()会为所有可用字重生成@font-face规则。
$font-prefix 与 $font-weights 的默认值与合并逻辑来自构建脚本生成的入口文件——从 scripts/tools/index.js 可以看到,入口 SCSS 会先声明 $font-prefix: '..' !default; 与空白的 $font-weights: () !default;,再用 map.merge 将你传入的覆盖值合并进完整字重清单,从而支持部分启用。
字重导入策略:all()、default() 与按需禁用
两种批量导入方式
PlexMono.all():导入全部 16 个字重(8 正体 + 8 斜体);PlexMono.default():只导入 light、regular、semibold 三个常用字重。
IBM Plex Mono 字重映射表(✅ 表示该字重被包含):
| 字重 | PlexMono.all() | PlexMono.default() |
|---|---|---|
| bold | ✅ | ✅ |
| boldItalic | ✅ | ❌ |
| extralight | ✅ | ❌ |
| extralightItalic | ✅ | ❌ |
| italic | ✅ | ❌ |
| light | ✅ | ❌ |
| lightItalic | ✅ | ❌ |
| medium | ✅ | ❌ |
| mediumItalic | ✅ | ❌ |
| regular | ✅ | ✅ |
| semibold | ✅ | ✅ |
| semiboldItalic | ✅ | ❌ |
| text | ✅ | ❌ |
| textItalic | ✅ | ❌ |
| thin | ✅ | ❌ |
| thinItalic | ✅ | ❌ |
在 @use 中禁用不需要的字重
如果只想保留少数几个字重,可以在 @use 时把其余字重显式设为 false:
// Disable weights
@use '@ibm/plex-mono/scss' as PlexMono with (
$font-weights: (
bold: false,
boldItalic: false,
extralight: false,
extralightItalic: false,
italic: false,
light: false,
lightItalic: false,
medium: false,
mediumItalic: false,
regular: false,
semibold: false,
semiboldItalic: false,
text: false,
textItalic: false,
thin: false,
thinItalic: false
)
);
@include PlexMono.all();
其底层机制是:每个字重的 mixin 都会先经过 tools.enabled($font-weights, 'xxx') 判断(见 scripts/tools/index.js),仅当对应键值为 true 时才输出该字重的 @font-face。因此「声明为 false + 调用 all()」等价于「只保留未禁用的字重」,可显著缩减最终 CSS 体积,避免为不需要的字重下载字体。
字重与数值、样式的对应关系
IBM Plex Mono 的字重命名与 CSS font-weight 数值的映射关系定义在 scripts/data/weights.js 中,这也是生成所有 @font-face 的依据:
| 字重 | font-style | font-weight |
|---|---|---|
| Thin | normal / italic | 100 |
| ExtraLight | normal / italic | 200 |
| Light | normal / italic | 300 |
| Regular | normal | 400 |
| Italic | italic | 400 |
| Text | normal / italic | 450 |
| Medium | normal / italic | 500 |
| SemiBold | normal / italic | 600 |
| Bold | normal / italic | 700 |
从 scripts/data/families.js 可以看到,plex-mono 家族声明了 hasItalic: true 并引用 monoUnicodeRanges 作为子集范围,因此 Mono 支持全部斜体变体与拆分子集。
font-family 规则
IBM Plex Mono 字族统一的 CSS 族名规则为:
font-family: 'IBM Plex Mono';
该名称在生成的每个 @font-face 中保持一致(见 scripts/tools/index.js),因此无论引入哪个字重,CSS 中只需声明一次族名,配合 font-weight / font-style 即可命中对应字体文件。
性能子集:split 字体与 unicode-range 原理
fonts/split/woff2/ 下的文件是性能优化的关键。每个字重被拆分为 5 个子集:Latin1、Latin2、Latin3、Cyrillic、Pi,每个子集对应独立的 @font-face 规则,并通过 unicode-range 声明覆盖的码位。浏览器只会下载当前页面实际用到的字符所在的子集文件,从而避免一次性加载整款字体。
子集拆分依据来自 scripts/data/unicodes/mono.js,例如:
- Latin1(
U+0020-007E等):基础拉丁与常用标点、货币符号、版权/商标符号; - Latin2:扩展拉丁(
U+0100-017F等)与多种货币符号; - Latin3:越南语等扩展拉丁组合(
U+1EA0-1EF9等); - Cyrillic:西里尔字母(
U+0400-045F等); - Pi:数学符号、箭头、制表符、框线字符(
U+2190-2199、U+2500-259F、U+03C0等)。
从源码结构看,每个字重的 SCSS 会生成两个 mixin:xxxComplete(引用 fonts/complete/woff2|woff 的完整文件)与 xxxSplit(遍历 $unicode-ranges,逐子集输出带 unicode-range 的 @font-face,引用 fonts/split/woff2 文件),最终由 all() 依次调用(详见 scripts/tools/index.js)。unicode-range 的值通过 tools.get-range() 从 unicodes.$ranges 映射表中取出。
因此,若追求极致加载性能,建议让构建工具仅输出 Split 部分的 @font-face(或直接使用 fonts/split/woff2/*.css),并优先使用体积更小的 woff2 格式。
从源码构建字体
如果你需要从设计源文件重新构建二进制字体,README 提供了完整工具链说明,仓库中也保留了对应脚本。
环境要求
| 组件 | 用途 |
|---|---|
| FontLab Studio 5 | 打开并编辑 .vfb 源文件 |
| Python + RoboFab 库 | 运行导出脚本 IBM Plex export FDK files.py |
| Adobe Font Development Kit for OpenType(AFDKO) | 提供 makeotf 命令行工具,生成 OTF/TTF |
仓库根目录下的 IBM Plex export FDK files.py(位于 scripts/ 目录)就是 README 所述的导出脚本。
构建单个字体的流程
- 在 FontLab 中运行
IBM Plex export FDK files.py,选择包含 IBM Plex.vfb源文件的目录; - 脚本会在该目录下新建
fdk文件夹,并为每个字体创建子目录,导出 AFDKO 所需的中间文件; - 在命令行使用 AFDKO 的
makeotf生成 OpenType(OTF)或 TrueType(TTF)字体。
makeotf 的详细用法可通过 makeotf -h 查看帮助。生成产物的典型输出目录结构与 fonts/complete/ 下的布局一致,可继续参与仓库的后续发布流程。
IBM Telemetry 说明
该包通过 IBM Telemetry 收集去标识化、匿名化的指标数据。安装 @ibm/plex-mono 作为依赖即表示同意遥测采集;若需退出,可按照 IBM Telemetry 官方文档中的 "Opting out of IBM Telemetry data collection" 指引设置环境变量禁用。
采集配置定义在 packages/plex-mono/telemetry.yml 中:其 projectId 为 722ea480-1271-4846-88a4-bd9fc12cbbcb,上报端点为 IBM 官方遥测接口,采集范围为 npm 依赖信息。该钩子通过 packages/plex-mono/package.json 中的 "postinstall": "ibmtelemetry --config=telemetry.yml" 触发,依赖 @ibm/telemetry-js。
深入仓库:SCSS 与字体是如何生成的
理解生成链路有助于你在集成时做出正确的取舍。仓库的 SCSS 并非手写,而是由 scripts/generate-scss.js 批量生成:
- 读取 scripts/data/families.js(家族元信息,
plex-mono声明了hasItalic: true与 Mono 专属 unicode 范围)与 scripts/data/weights.js(字重数值表); - 为每个家族生成
scss/下的入口index.scss、tools/与unicodes/辅助模块、各字重的 partial 文件,以及用于产出 CSS 的临时文件css-all.scss/css-default.scss; - 各字重 partial 中的
@font-face结构(font-family、font-style、font-weight、src: local(...), url(...woff2) format('woff2'), url(...woff) format('woff'))同样来自 scripts/tools/index.js 的模板。
仓库 test/index.html 与 test/index-cdn.html 提供了多字重、多子集渲染的本地预览页,可用于验证字体是否被正确加载与回退。
小结
接入 IBM Plex Mono 时,可按需选择三条路径:桌面/终端使用选择 fonts/complete/ 下的 OTF/TTF;追求开箱即用选择 npm 包中的 CSS;追求体积与可控性则使用 SCSS 模块,配合 $font-prefix 修正路径、PlexMono.all()/default() 与 $font-weights 控制字重输出,并结合 fonts/split/woff2 的 unicode-range 子集实现按需加载。若需从设计源头二次开发字体,仓库还提供了完整的 FontLab + RoboFab + AFDKO 构建脚本供参考。