@font-face必须声明在全局css文件中，不能放入css modules文件；因其不参与局部化且构建工具可能忽略或导致注册失败，应集中放在如src/assets/fonts.css中并由主入口显式引入。
@font-face 声明必须写在全局作用域，不能放在 CSS Modules 文件里
CSS Modules 会对所有选择器自动加哈希后缀（如 .title_abc123），但 @font-face 是规则级声明，不参与局部化——它只认 font-family 字符串名，跟作用域无关。一旦你把它写进 Button.module.css，Webpack 或 Vite 构建时可能直接忽略，或导致字体注册失败（尤其在 SSR 或多 chunk 场景下）。
实操建议：
- 把所有
@font-face集中写在src/assets/fonts.css这类纯 CSS 入口文件中，并确保该文件被主入口（如main.tsx）显式 import - 不要用
import './fonts.css'在某个组件模块里“就近引入”，那等于白写 - 若用 Vite，确认
assets/fonts.css没被css.modules配置误匹配（Vite 默认只对*.module.css启用 modules）
font-family 名称在 CSS Modules 中引用时不能加引号包裹（除非含空格或特殊字符）
你在全局 fonts.css 里定义了 font-family: 'InterVar';，那么在 Button.module.css 里写 font-family: InterVar; 即可。加单/双引号反而容易触发解析歧义，尤其当构建工具做 CSS 压缩或 postcss 处理时。
常见错误现象：
- 写了
font-family: 'InterVar', sans-serif;，但浏览器 DevTools 显示实际生效的是sans-serif—— 很可能是引号导致匹配失败 - 字体名含空格（如
'IBM Plex Sans'）才必须加引号；纯英文无空格名（InterVar、HarmonyOS_Sans）一律不加 - 大小写需严格一致：全局定义是
font-family: intervar;，模块里就不能写InterVar
路径问题：CSS Modules 中的 url() 不会自动解析相对路径到字体文件
CSS Modules 本身不改写 url()，但构建工具（如 Webpack 的 css-loader）默认按 CSS 文件所在位置解析相对路径。如果你把 @font-face 放在 src/assets/fonts.css，而字体文件在 src/assets/fonts/inter-var.woff2，那 url('./inter-var.woff2') 才正确；若误写成 url('../fonts/inter-var.woff2')，构建时会报 Module not found 或生成 404 请求。
实操建议：
- 统一用以
src/assets/fonts/为基准的相对路径，例如url('./inter-var.woff2') - 避免使用
../向上跳转，容易因文件移动失效 - Vite 用户可直接用
url('/fonts/inter-var.woff2')（public 目录下），路径更稳 - Webpack 用户若启用了
resolve.alias，可配@fonts: './src/assets/fonts'，然后写url('@fonts/inter-var.woff2')
font-display 和 preload 必须手动配，CSS Modules 不接管这些行为
font-display: swap 能防止文字隐形（FOIT），但它不会因为用了 CSS Modules 就自动生效。同样，<link rel="preload"> 也得你手写进 HTML 或用插件注入，CSS Modules 文件里加不了。
关键点：
- 在
@font-face块里显式写font-display: swap;，别依赖浏览器默认 - 如果字体是首屏关键字体（比如 logo 文字），务必在
index.html里加：<link rel="preload" href="/fonts/inter-var.woff2" as="font" type="font/woff2" crossorigin>
—— 注意crossorigin属性，否则字体即使预加载了也无法使用 - 不加
crossorigin是最常被忽略的坑：字体请求会被当作“带凭据”处理，而 CDN 或 public 目录通常不返回Access-Control-Allow-Origin，结果就是静默失败
真正麻烦的不是语法，而是字体注册时机和资源加载链路的耦合——@font-face 声明、路径解析、CORS、preload、CSS 优先级，任何一个环节断掉，用户看到的都只是系统字体，连控制台都未必报错。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
