@font-face 中 src: local() 无法通过字体显示名称（如 "PingFang SC"）直接映射，必须使用系统内部注册的字体家族精确名称（如 PingFangSC-Regular），且不同字重需单独声明。
`@font-face` 中 `src: local()` 无法通过字体显示名称（如 "pingfang sc"）直接映射，必须使用系统内部注册的字体家族精确名称（如 `pingfangsc-regular`），且不同字重需单独声明。
在 Web 开发中，我们常希望通过 @font-face 的 local() 源为已安装的系统字体创建语义化别名（例如用 "Test" 代替 "PingFang SC"），以提升 CSS 可维护性或实现设计系统抽象。但实践中，类似以下写法往往失效：
@font-face {
font-family: "Test";
src: local(PingFang SC); /* ❌ 错误：含空格、非注册名 */
}
根本原因在于：local() 函数匹配的是操作系统字体注册表中的 PostScript 名称 或 完整字体家族名（无空格、无标点），而非用户界面中显示的友好名称（Display Name）。macOS 中 "PingFang SC" 在系统底层实际注册为 PingFangSC-Regular（常规体）、PingFangSC-Semibold、PingFangSC-Medium 等，而 PingFang SC 本身并非有效本地标识符。
✅ 正确做法是：
-
查询真实字体内部名称：
- macOS：在“字体册”中双击字体 → “字体信息” → 查看“PostScript 名称”或“完整名称”（去掉空格与标点）；
- 或终端执行：
system_profiler SPFontsDataType | grep -A5 "PingFang"；
-
为每个需要的字重单独声明
@font-face：
/* ✅ 正确示例：为 PingFang SC 各字重定义别名 */
@font-face {
font-family: "Test";
font-weight: 400;
src: local(PingFangSC-Regular);
}
@font-face {
font-family: "Test";
font-weight: 600;
src: local(PingFangSC-Semibold);
}
@font-face {
font-family: "Test";
font-weight: 500;
src: local(PingFangSC-Medium);
}
.with-font {
font-family: "Test", -apple-system, system-ui; /* 回退链不可少 */
}
⚠️ 注意事项：
-
local()不支持通配符或模糊匹配，local("PingFang SC")和local(PingFang\ SC)均无效； - 浏览器对
local()的支持存在差异（Safari 最稳定，Chrome/Firefox 对某些系统字体可能降级为回退字体）； -
永远提供合理的字体回退链（如
-apple-system,BlinkMacSystemFont,system-ui），避免因匹配失败导致文本渲染异常； - 不建议依赖
local()构建核心排版逻辑——它本质是性能优化手段，而非可靠字体控制方案；如需强一致性，应优先考虑url()加载 WOFF2 字体。
总结：@font-face 的 local() 是“捷径”，不是“别名生成器”。成功的关键在于精准定位系统字体的底层注册名，并按字重粒度显式声明。将 "Test" 作为设计系统中的语义化字体代号时，请同步维护一份对应各平台真实字体名的映射表，才能真正实现跨环境可控的字体抽象。
