如何在 SCSS 模块中正确导入并使用自定义字体

本文详解在 SCSS 模块化项目（如 React + CSS Modules）中导入本地 Google 字体的完整流程，涵盖 @font-face 声明、路径配置、引用语法及常见错误（如字体名引号缺失、大小写/空格不一致等），确保字体成功渲染。

本文详解在 scss 模块化项目（如 react + css modules）中导入本地 google 字体的完整流程，涵盖 `@font-face` 声明、路径配置、引用语法及常见错误（如字体名引号缺失、大小写/空格不一致等），确保字体成功渲染。

在基于 SCSS 的模块化前端项目（例如使用 .module.scss 文件的 React 应用）中，正确引入并应用自定义字体需兼顾 声明规范 与 引用一致性。你已在 fonts.scss 中通过 @font-face 注册了 Poller One 和 Raleway 字体，这是正确的第一步；但问题往往出在后续调用环节。

✅ 正确用法：字体名必须加引号且严格匹配

CSS 规范要求：当 font-family 名称包含空格、数字或特殊字符（如 Poller One）时，必须使用英文双引号包裹。否则浏览器会将其解析为多个独立的字体名（如 Poller 和 One），导致回退到系统默认字体。

// ✅ 正确：在 home.module.scss 中引用@import "../../fonts.scss";h1 {  font-family: "Poller One", "Raleway", sans-serif;}

注意：font-family 值中的 "Poller One" 必须与 @font-face 中 font-family: "Poller One" 的字符串完全一致（包括大小写、空格、标点）。建议统一复制粘贴避免手误。

? 补充关键检查项

1. 路径有效性：确认 ./Fonts/PollerOne.ttf 相对于 fonts.scss 文件的路径真实存在，且构建工具（如 Webpack、Vite）已配置支持 .ttf 文件加载（通常需 file-loader 或 asset/resource 类型）。
2. 字体格式兼容性：.ttf 在现代浏览器中广泛支持，但为更好兼容性，可补充 woff2（推荐优先）和 woff 格式：

   @font-face {  font-family: "Poller One";  src: local("Poller One"),       url("./Fonts/PollerOne.woff2") format("woff2"),       url("./Fonts/PollerOne.ttf") format("truetype");  font-weight: normal;  font-style: normal;}

3. SCSS 模块作用域限制：.module.scss 文件默认启用 CSS Modules，但 @import 引入的全局样式（如字体声明）不受模块化影响——@font-face 是全局注册行为，因此 home.module.scss 中可直接使用，无需额外导出。

? 验证是否生效

1. 打开浏览器开发者工具 → Elements 面板，选中 <h1> 元素；
2. 查看 Computed 标签页中的 font-family，确认显示 "Poller One" 且 src 指向你的本地 .ttf 文件；
3. 若显示 font-family: serif 或其他回退字体，请检查控制台是否有 404（字体文件路径错误）或 CORS 报错。

✅ 总结

导入本地字体 ≠ 仅写 @font-face。核心三要素缺一不可：

① @font-face 中 font-family 命名规范（带引号、无歧义）；

② 使用处 font-family 值严格复刻声明名（含引号）；

③ 文件路径可访问 + 构建工具支持字体资源处理。

遵循以上步骤，即可稳定在 SCSS 模块中启用任意 Google Fonts 下载字体。