CLI 与 Node 库
fontstay 包就是本站的匹配引擎,只是脱离了浏览器:它是一个命令行工具和 Node 库,读取字体文件,并输出与本应用相同的 @font-face 规则和导出内容。它不需要 DOM,也不发出任何网络请求,因此适合构建流水线和 CI。
安装
该包尚未发布到 npm。它需要 Node 24 或更高版本;请从代码仓库副本构建。下面的示例用 fontstay 代表 node packages/fontstay/dist/bin.js。
git clone https://github.com/fogrew/fontstay.dev.git
cd fontstay.dev
pnpm install
pnpm cli:build
node packages/fontstay/dist/bin.js --version命令
fit 读取一个或多个字体文件(WOFF2、WOFF、TTF、OTF)并输出回退 CSS。多个文件会合并为一份样式表,与应用中一样。mcp 在 stdio 上为编码智能体启动 MCP 服务器,不接受任何选项。
为 Windows 和 macOS 匹配一个字体,不含西里尔文和希腊文字体面。输出与应用中的 CSS 导出内容相同。
$ fontstay fit font.woff2 --systems windows,macos --no-scripts
@font-face {
font-family: "Source Sans Pro Fallback";
src: local("Arial"), local("ArialMT");
size-adjust: 93.697%;
ascent-override: 105.0194%;
descent-override: 29.1365%;
line-gap-override: 0%;
}
body {
font-family: "Source Sans Pro", "Source Sans Pro Fallback", sans-serif;
/* Safari has no vertical overrides: match the x-height and fix the line box */
font-size-adjust: 0.48;
line-height: 1.4;
}
.fonts-loading {
letter-spacing: -0.0003em;
word-spacing: -0.0025em;
}fontstay fit Inter.woff2 -o fallbacks.css
fontstay fit regular.woff2 bold.woff2 --format tailwind
fontstay fit font.woff2 -a 'last 2 chrome versions, os windows' --json选项
| 选项 | 含义 |
|---|---|
-s, --systems <list> | 要匹配的系统:windows、macos、ios、android、linux、chromeos。默认:受众中占比至少 1% 的每个系统。 |
-a, --audience <query> | Browserslist 查询,可附带“os <system>”和“not os <system>”部分。默认:Baseline 广泛可用。 |
-f, --format <format> | 输出格式,见下文。默认:css。 |
-k, --kind <kind> | 回退字体的通用字体族:sans-serif、serif、monospace 或 cursive。默认:根据字体检测。 |
--locale <en|ru> | 匹配所用的频率配置:en 或 ru。默认:en。 |
--unicode-range | 添加 unicode-range,包含每个字体覆盖的字形。 |
--no-scripts | 不为西里尔文和希腊文单独输出字体面。 |
-o, --out <file> | 把输出写入文件,而不是 stdout。 |
--json | 输出 JSON 报告,而不是文件文本。 |
-h, --help / -v, --version | 显示帮助或版本。 |
输出格式
--format 接受下列值之一。它们与应用的导出格式对应,并基于同一匹配结果。
使用示例 Fira Sans 字体,为每种格式运行此命令。所示输出来自已构建的 CLI。
命令
fontstay fit tests/fixtures/fonts/FiraSans-Regular.ttf --systems windows --no-scripts --format cssCLI 输出
@font-face {
font-family: "Fira Sans Fallback";
src: local("Trebuchet MS"), local("TrebuchetMS");
size-adjust: 100.3942%;
ascent-override: 93.1328%;
descent-override: 26.3959%;
line-gap-override: 0%;
}
body {
font-family: "Fira Sans", "Fira Sans Fallback", sans-serif;
/* Safari has no vertical overrides: match the x-height and fix the line box */
font-size-adjust: 0.527;
line-height: 1.4;
}
.fonts-loading {
letter-spacing: -0.0019em;
}命令
fontstay fit tests/fixtures/fonts/FiraSans-Regular.ttf --systems windows --no-scripts --format variablesCLI 输出
@font-face {
font-family: "Fira Sans Fallback";
src: local("Trebuchet MS"), local("TrebuchetMS");
size-adjust: 100.3942%;
ascent-override: 93.1328%;
descent-override: 26.3959%;
line-gap-override: 0%;
}
:root {
--font-body: "Fira Sans", "Fira Sans Fallback", sans-serif;
}
body {
font-family: var(--font-body);
/* Safari has no vertical overrides: match the x-height and fix the line box */
font-size-adjust: 0.527;
line-height: 1.4;
}命令
fontstay fit tests/fixtures/fonts/FiraSans-Regular.ttf --systems windows --no-scripts --format tailwindCLI 输出
@import "tailwindcss";
@font-face {
font-family: "Fira Sans Fallback";
src: local("Trebuchet MS"), local("TrebuchetMS");
size-adjust: 100.3942%;
ascent-override: 93.1328%;
descent-override: 26.3959%;
line-gap-override: 0%;
}
@theme {
--font-sans: "Fira Sans", "Fira Sans Fallback", sans-serif;
}命令
fontstay fit tests/fixtures/fonts/FiraSans-Regular.ttf --systems windows --no-scripts --format nextCLI 输出
// Put FiraSans-Regular.ttf into ./fonts/ and the @font-face rules from the CSS export into your global CSS.
import localFont from 'next/font/local';
export const font = localFont({
src: './fonts/FiraSans-Regular.ttf',
display: 'swap',
adjustFontFallback: false,
fallback: ['Fira Sans Fallback', 'sans-serif'],
variable: '--font-body',
});命令
fontstay fit tests/fixtures/fonts/FiraSans-Regular.ttf --systems windows --no-scripts --format nuxtCLI 输出
// Add the @font-face rules from the CSS export to a stylesheet listed in `css`.
export default defineNuxtConfig({
modules: ['@nuxt/fonts'],
fonts: {
families: [
{
name: 'Fira Sans',
src: '/fonts/FiraSans-Regular.ttf',
fallbacks: ['Fira Sans Fallback', 'sans-serif'],
},
],
},
});命令
fontstay fit tests/fixtures/fonts/FiraSans-Regular.ttf --systems windows --no-scripts --format astroCLI 输出
// Add the @font-face rules from the CSS export to your global styles.
import { defineConfig } from 'astro/config';
export default defineConfig({
fonts: [
{
name: 'Fira Sans',
cssVariable: '--font-body',
provider: 'local',
options: {
variants: [{ weight: 400, style: 'normal', src: ['./src/assets/fonts/FiraSans-Regular.ttf'] }],
},
fallbacks: ['Fira Sans Fallback', 'sans-serif'],
},
],
});命令
fontstay fit tests/fixtures/fonts/FiraSans-Regular.ttf --systems windows --no-scripts --format wordpressCLI 输出
{
"$schema": "https://schemas.wp.org/trunk/theme.json",
"version": 3,
"settings": {
"typography": {
"fontFamilies": [
{
"name": "Fira Sans",
"slug": "fira-sans",
"fontFamily": "\"Fira Sans\", \"Fira Sans Fallback\", sans-serif",
"fontFace": [
{
"fontFamily": "Fira Sans",
"fontWeight": "400",
"fontStyle": "normal",
"src": [
"file:./assets/fonts/FiraSans-Regular.ttf"
]
}
]
}
]
}
}
}命令
fontstay fit tests/fixtures/fonts/FiraSans-Regular.ttf --systems windows --no-scripts --format fontaineCLI 输出
// Put FiraSans-Regular.ttf into ./public/fonts/ and declare their @font-face rules in your CSS. In Nuxt, put the plugin under vite.plugins.
import { FontaineTransform } from 'fontaine';
import { defineConfig } from 'vite';
export default defineConfig({
plugins: [
FontaineTransform.vite({
fallbacks: {
'Fira Sans': ['Trebuchet MS'],
},
resolvePath: (id) => new URL(`./public${id}`, import.meta.url),
}),
],
});命令
fontstay fit tests/fixtures/fonts/FiraSans-Regular.ttf --systems windows --no-scripts --format preloadCLI 输出
<link rel="preload" href="/fonts/FiraSans-Regular.ttf" as="font" type="font/ttf" crossorigin>命令
fontstay fit tests/fixtures/fonts/FiraSans-Regular.ttf --systems windows --no-scripts --format loadingCLI 输出
const root = document.documentElement;
const done = () => root.classList.remove('fonts-loading');
root.classList.add('fonts-loading');
document.fonts.load('1em "Fira Sans"').then(done, done);输出与报告
文件文本输出到 stdout。使用 --json 时,CLI 改为输出报告,包含这些键:file(所选格式的输出)、fonts(每个字体的字体族、检测到的类型、字形覆盖率,以及为每个系统选出的回退字体)、shares(各系统的受众占比,单位为百分比)、systems、uncovered(受众中没有回退字体的系统)和 audience(解析出的查询及匹配的浏览器数量)。占比取决于运行时的浏览器数据。
警告输出到 stderr,因此不会混入输出内容:回退字体与其共有字形不足 90% 的字体,以及没有任何回退字体的系统。使用 --out 时,CLI 还会在 stderr 上报告所写入的文件。
Node 库
fit 接受字体字节,fitFiles 读取文件。两者都返回 CSS、所请求格式的输出、每个字体的报告以及受众占比。失败时会抛出 FitRunError(invalid-audience、no-systems、no-fit)或 FontParseError(例如 invalid-font)。类型定义在 index.d.ts 中。
import { fit, fitFiles } from 'fontstay';
import { readFile } from 'node:fs/promises';
const { css, fonts, shares } = await fit({
fonts: [{ fileName: 'font.woff2', data: await readFile('font.woff2') }],
audience: 'defaults',
systems: ['windows', 'macos'],
});
const tailwind = (await fitFiles(['font.woff2'], { format: 'tailwind' })).file.text;退出码
| 代码 | 含义 |
|---|---|
0 | 成功。 |
1 | 失败:文件无法读取、字体无效、受众无效。 |
2 | 用法错误:未知命令、没有字体文件、选项值无效。 |