本文介绍如何在 React 项目中根据 .env 文件动态加载不同字体资源，避免硬编码路径，支持开发、测试、生产等多环境差异化字体部署，核心采用 FontFace API 实现运行时按需加载与注入。
本文介绍如何在 react 项目中根据 `.env` 文件动态加载不同字体资源，避免硬编码路径，支持开发、测试、生产等多环境差异化字体部署，核心采用 `fontface api` 实现运行时按需加载与注入。
在 React 应用中，将字体路径与环境解耦是提升可维护性与部署灵活性的关键实践。由于 CSS/SCSS 无法直接读取 process.env（尤其在构建时静态编译），传统方式如在 font.scss 中引用 JS 变量不可行——Sass 编译发生在 JS 运行前，二者上下文隔离。因此，推荐采用 运行时动态加载 策略，结合环境变量控制字体源。
✅ 推荐方案：FontFace API + 环境驱动配置
FontFace 是现代浏览器原生支持的字体加载接口，允许 JavaScript 动态创建、加载并注册字体族，完全绕过 CSS 文件路径限制。配合 REACT_APP_FONT_BASE_URL 等自定义环境变量，可实现真正的“一码多环境”。
? 步骤一：配置环境变量
在项目根目录下创建或编辑 .env、.env.development、.env.production：
# .env.development REACT_APP_FONT_BASE_URL=https://cdn-dev.example.com/fonts/ # .env.production REACT_APP_FONT_BASE_URL=https://cdn-prod.example.com/fonts/
⚠️ 注意：所有自定义环境变量必须以
REACT_APP_开头，才能被 Create React App 自动注入到process.env中。
? 步骤二：封装动态字体加载工具函数
新建 src/utils/fontLoader.js：
/**
* 动态加载并注册字体
* @param {string} family - 字体族名（如 'Inter'）
* @param {string} fileName - 字体文件名（如 'Inter-Regular.woff2'）
* @param {Object} [options={}] - FontFace 构造选项（如 weight, style）
* @returns {Promise<void>}
*/
export const loadFont = async (family, fileName, options = {}) => {
const baseUrl = process.env.REACT_APP_FONT_BASE_URL;
if (!baseUrl) {
throw new Error('REACT_APP_FONT_BASE_URL is not defined in environment');
}
const url = `${baseUrl}${fileName}`;
const fontFace = new FontFace(family, `url(${url})`, options);
try {
const loadedFont = await fontFace.load();
document.fonts.add(loadedFont);
} catch (err) {
console.error(`Failed to load font "${family}" from ${url}:`, err);
throw err;
}
};
/**
* 批量加载多个字体（推荐用于初始化）
*/
export const loadMultipleFonts = async (fontConfigs) => {
const loadPromises = fontConfigs.map(({ family, file, ...opts }) =>
loadFont(family, file, opts)
);
await Promise.all(loadPromises);
};? 步骤三：在应用入口处统一加载（如 src/index.js 或 App.js）
import React from 'react';
import ReactDOM from 'react-dom/client';
import './index.css';
import App from './App';
import { loadMultipleFonts } from './utils/fontLoader';
// 定义各环境共用的字体清单（路径由 env 决定，名称与样式保持一致）
const FONT_CONFIGS = [
{ family: 'Inter', file: 'Inter-Regular.woff2', weight: '400' },
{ family: 'Inter', file: 'Inter-SemiBold.woff2', weight: '600' },
{ family: 'IBM Plex Sans', file: 'IBMPlexSans-Regular.woff2', weight: '400' },
];
// 启动时预加载关键字体
loadMultipleFonts(FONT_CONFIGS)
.then(() => console.log('✅ All fonts loaded and registered'))
.catch(err => console.warn('⚠️ Font loading partially failed:', err));
const root = ReactDOM.createRoot(document.getElementById('root'));
root.render(<App />);? 步骤四：CSS 中安全使用字体族（无需 @font-face 声明）
/* src/index.css */
body {
font-family: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
}
h1 {
font-family: 'Inter', sans-serif;
font-weight: 600; /* 对应加载的 SemiBold */
}✅ 优势说明：因字体已通过
document.fonts.add()注册，CSS 中可直接引用font-family，浏览器会自动匹配已加载的weight/style，无需重复声明@font-face。
? 注意事项与最佳实践
-
字体格式兼容性：优先使用
woff2（现代浏览器支持好、体积小），必要时为旧浏览器提供woff回退（需额外配置loadFont多格式尝试逻辑）。 -
加载时机：建议在
index.js中尽早调用，确保样式渲染前字体就绪；如需按需加载（如模态框专用字体），可在组件useEffect中触发。 -
错误降级：
FontFace.load()可能失败（如 CDN 不可达），务必添加try/catch并提供默认字体栈，保障 UI 可用性。 -
性能考量：避免一次性加载过多字体；可结合
IntersectionObserver或用户操作（如点击切换主题）按需加载非核心字体。 -
TypeScript 支持：若使用 TS，可为
loadFont添加完整类型定义，增强开发体验。
通过该方案，你不仅实现了字体路径的环境动态化，更获得了细粒度控制能力——包括加载状态反馈、错误监控、按需注入等，远超静态 CSS 方案的灵活性与健壮性。
