postcss-font-guard

构建阶段字体管控插件，自动识别并剔除侵权字体风险。

快速上手

npm install postcss-font-guard --save-dev

// postcss.config.js
module.exports = {
  plugins: [require("postcss-font-guard")()],
};

无需任何配置。自动保留项目自定义字体（@font-face 声明的）和 CSS 通用族（sans-serif、system-ui、-apple-system 等），剔除其余系统字体名，用 sans-serif 兜底。

/* 输入 */
@font-face { font-family: "DIN-Bold"; src: url('/fonts/DIN-Bold.woff2'); }
body { font-family: -apple-system, BlinkMacSystemFont, "Helvetica Neue", Arial, "PingFang SC", sans-serif; }
.price { font-family: "DIN-Bold", Arial, sans-serif; }
.label { font-family: Arial; }

/* 输出 */
@font-face { font-family: "DIN-Bold"; src: url('/fonts/DIN-Bold.woff2'); }
body { font-family: -apple-system, BlinkMacSystemFont, sans-serif; }
.price { font-family: "DIN-Bold", sans-serif; }
.label { font-family: sans-serif; }

配置项

零配置满足大多数场景。以下选项用于特殊需求：

| 选项 | 类型 | 默认值 | 说明 | |---|---|---|---| | fallback | string \| string[] \| null | "sans-serif" | 字体清空后的兜底值；设为 null 则移除空声明 | | allow | string[] \| (name) => boolean | - | 白名单模式，只保留匹配的字体 | | deny | string[] | - | 黑名单模式，只删除匹配的字体 | | override | string | - | 所有字体替换为此值 | | removeImports | string[] | - | 删除含指定域名的 @import | | fontVariables | string[] | 自动检测 | 需过滤的 CSS 变量名（默认自动检测 --*font-family*） | | verbose | boolean | false | 输出修改日志 |

优先级：override > allow > deny > 零配置智能模式

sans-serif、system-ui、-apple-system、BlinkMacSystemFont 等 CSS 通用族 / 厂商关键字和 var() / env() 表达式始终保留。allow 和 deny 支持 * / ? 通配符。

场景示例

自定义兜底字体

require("postcss-font-guard")({ fallback: ["NotoSans-Thai", "sans-serif"] })

白名单：只保留指定字体

require("postcss-font-guard")({ allow: ['DIN*', 'Roboto*'] })

匹配的字体保留，其余删除。适合明确知道项目使用了哪些字体的场景。

黑名单：只删除指定字体

require("postcss-font-guard")({ deny: ['Helvetica Neue', 'Arial', 'PingFang SC'] })

匹配的字体删除，其余保留。适合只需移除少量已知侵权字体的场景。

全量替换

require("postcss-font-guard")({ override: "Inter, sans-serif" })

所有 font-family 和 font 简写统一替换，最简单粗暴的方式。

移除字体 @import

require("postcss-font-guard")({ removeImports: ['fonts.googleapis.com'] })

CSS 变量自动过滤

自动识别并过滤变量名含 font-family 的 CSS 自定义属性（如 --adm-font-family）。非字体值（颜色、尺寸等）自动跳过，不会误改：

/* 输入 */  :root { --adm-font-family: -apple-system, Helvetica, Arial, sans-serif; }
/* 输出 */  :root { --adm-font-family: -apple-system, sans-serif; }

/* 非字体值不受影响 */
:root { --font-family-color: #fff; }       /* 不变 */
:root { --font-family-size: 16px; }        /* 不变 */

var() / env() 回退值中的侵权字体也会被过滤：

/* 输入 */  font-family: var(--font, "Helvetica Neue"), sans-serif;
/* 输出 */  font-family: var(--font), sans-serif;

如需过滤不含 font-family 的变量，用 fontVariables 显式指定：

require("postcss-font-guard")({ fontVariables: ['--theme-font', '--*-stack'] })

构建工具集成

Webpack / rspack：

// postcss.config.js
module.exports = {
  plugins: [require("postcss-font-guard")()],
};

Vite：

import fontGuard from "postcss-font-guard";
export default {
  css: { postcss: { plugins: [fontGuard()] } },
};

配合 Tailwind CSS：

Tailwind preflight 会注入系统字体栈，建议同时配置 Tailwind 字体：

// tailwind.config.js
module.exports = {
  theme: { fontFamily: { sans: ['NotoSans-Thai', 'sans-serif'] } },
};

兼容性

• PostCSS 8.0+
• 零运行时依赖

License

MIT