本文介绍如何在 React 应用中根据 .env 文件动态加载不同字体资源，避免硬编码路径，实现开发、测试、生产环境的字体路径隔离与按需加载。
本文介绍如何在 react 应用中根据 `.env` 文件动态加载不同字体资源，避免硬编码路径，实现开发、测试、生产环境的字体路径隔离与按需加载。
在现代前端工程中，字体资源常因部署环境（如本地开发、Staging、生产）而需指向不同 CDN 或本地路径。直接在 CSS/SCSS 中写死 @font-face 路径会导致环境耦合，且无法在构建后动态切换——尤其当字体托管在不同域名或需鉴权时，静态编译方式难以满足需求。React 应用推荐采用 运行时动态注入 FontFace API 方案，结合环境变量实现真正“环境感知”的字体加载。
✅ 推荐方案：运行时动态加载（FontFace API）
FontFace 是现代浏览器原生支持的 API，允许 JavaScript 动态注册字体族，并在加载完成后立即应用。配合 process.env.REACT_APP_FONT_BASE_URL 等自定义环境变量，可实现路径完全动态化：
// utils/fontLoader.js
export const loadFont = async (family, fileName, options = {}) => {
const baseUrl = process.env.REACT_APP_FONT_BASE_URL || '';
const url = `${baseUrl}/${fileName}`;
try {
const fontFace = new FontFace(family, `url(${url})`, options);
const loadedFont = await fontFace.load();
document.fonts.add(loadedFont);
console.log(`✅ Font '${family}' loaded from ${url}`);
} catch (err) {
console.error(`❌ Failed to load font '${family}':`, err);
}
};
// 批量加载多个字体（支持 Promise.all 并发）
export const loadMultipleFonts = async (fontConfigs) => {
const promises = fontConfigs.map(({ family, file, ...opts }) =>
loadFont(family, file, opts)
);
await Promise.all(promises);
};
? 在组件中使用示例
// components/ThemedText.jsx
import { useEffect } from 'react';
import { loadMultipleFonts } from '../utils/fontLoader';
const ThemedText = () => {
useEffect(() => {
// 根据环境变量决定加载哪组字体
const fontConfigs = [
{ family: 'Inter', file: 'Inter-Regular.woff2' },
{ family: 'IBM Plex Sans', file: 'IBMPlexSans-Regular.woff2' },
{ family: 'Avenir Next', file: 'AvenirNext-Medium.woff2' },
];
loadMultipleFonts(fontConfigs);
}, []);
return <h1 style="{{" fontfamily: plex sans sans-serif>
这段文字将使用动态加载的字体渲染
</h1>;
};
export default ThemedText;
⚙️ 环境变量配置（.env 示例）
# .env.development REACT_APP_FONT_BASE_URL=/fonts/dev # .env.production REACT_APP_FONT_BASE_URL=https://cdn.example.com/fonts/prod # .env.staging REACT_APP_FONT_BASE_URL=https://staging-cdn.example.com/fonts
✅ 优势说明：
- ✅ 完全脱离 CSS 预处理器限制（无需 SCSS 变量注入）；
- ✅ 支持按需加载、错误捕获与回退逻辑；
- ✅ 字体加载完成后再应用样式，避免 FOIT/FOUT 不可控；
- ✅ 与 Webpack/Vite 构建流程零耦合，兼容 CRA、Vite、Next.js 等所有 React 生态。
⚠️ 注意事项
-
FontFace.load()返回 Promise，务必await或.catch()处理失败； - 浏览器兼容性：Chrome 35+、Firefox 41+、Safari 10.1+、Edge 17+（Can I use FontFace）；
- 若需 SSR 支持（如 Next.js），请仅在客户端执行加载逻辑（
typeof window !== 'undefined'判断）； - 建议为字体文件启用
font-display: swap（通过@font-face的display属性），但注意：动态创建的FontFace实例不支持display属性，需在预置的 CSS 中声明基础 fallback 行为。
通过该方案，你不再需要维护多套 SCSS 变量或条件编译 CSS，真正实现「一套代码、多环境字体路径自动适配」，提升可维护性与部署灵活性。
