本文介绍在 React 项目中基于 .env 文件动态配置字体路径并按需加载的完整方案，涵盖运行时动态注入 @font-face、环境变量集成、CSS 模块化处理及最佳实践。
本文介绍在 react 项目中基于 `.env` 文件动态配置字体路径并按需加载的完整方案，涵盖运行时动态注入 `@font-face`、环境变量集成、css 模块化处理及最佳实践。
在 React 应用中实现“按环境动态加载多种字体”，核心在于将字体路径从硬编码解耦为环境驱动的运行时配置，并确保字体资源在页面渲染前或需要时可靠注入。直接在 SCSS 中引用 JS 环境变量不可行（因 CSS/SCSS 编译早于 JS 运行），因此推荐采用 JavaScript 动态注册 FontFace + 环境变量预置路径 的组合方案。
✅ 推荐方案：环境感知的 FontFace 动态加载
首先，在 .env 文件中定义字体路径（支持多环境）：
# .env.development REACT_APP_FONT_PRIMARY_URL=/fonts/Inter-Regular.woff2 REACT_APP_FONT_HEADER_URL=/fonts/SpaceGrotesk-Bold.woff2 # .env.production REACT_APP_FONT_PRIMARY_URL=https://cdn.example.com/fonts/Inter-Regular.woff2 REACT_APP_FONT_HEADER_URL=https://cdn.example.com/fonts/SpaceGrotesk-Bold.woff2
⚠️ 注意：
REACT_APP_前缀是 Create React App 的强制要求，自定义变量才能被 Webpack 注入到客户端。
接着，创建 src/utils/fontLoader.js，封装可复用的字体加载逻辑：
// src/utils/fontLoader.js
export const loadFonts = async (fonts) => {
const fontPromises = fonts.map(({ family, url, options = {} }) => {
if (!url) throw new Error(`Missing font URL for family: ${family}`);
const fontFace = new FontFace(family, `url(${url})`, options);
return fontFace.load().then((loadedFont) => document.fonts.add(loadedFont));
});
await Promise.all(fontPromises);
};
// 使用示例：按环境批量加载
export const initAppFonts = async () => {
const fonts = [
{
family: 'Inter',
url: process.env.REACT_APP_FONT_PRIMARY_URL
},
{
family: 'Space Grotesk',
url: process.env.REACT_APP_FONT_HEADER_URL,
options: { weight: '700' }
}
];
await loadFonts(fonts);
};在应用入口（如 src/index.js 或 src/App.js 的 useEffect 中）调用初始化：
// src/index.js
import React from 'react';
import ReactDOM from 'react-dom/client';
import './index.css';
import App from './App';
import { initAppFonts } from './utils/fontLoader';
// 首屏前预加载关键字体（提升渲染一致性）
initAppFonts().catch(console.error);
const root = ReactDOM.createRoot(document.getElementById('root'));
root.render(<App />);✅ 进阶：按需加载 + 样式绑定（适用于主题切换或模块化字体）
若需在组件内动态切换字体（如用户选择），可结合 useState 和内联样式：
// ExampleComponent.jsx
import { useState, useEffect } from 'react';
import { loadFonts } from '../utils/fontLoader';
export default function ExampleComponent() {
const [activeFont, setActiveFont] = useState('Inter');
useEffect(() => {
// 仅当切换时加载新字体（避免重复）
if (activeFont === 'Space Grotesk') {
loadFonts([{ family: 'Space Grotesk', url: process.env.REACT_APP_FONT_HEADER_URL }]);
}
}, [activeFont]);
return (
<div>
<h1 style={{ fontFamily: activeFont }}>动态字体示例</h1>
<button onClick={() => setActiveFont('Inter')}>切到 Inter</button>
<button onClick={() => setActiveFont('Space Grotesk')}>切到 Space Grotesk</button>
</div>
);
}? 注意事项与最佳实践
-
字体加载时机：
document.fonts.add()仅注册字体，不保证立即可用；建议配合document.fonts.load()或font-display: swap（在 CSS 中声明）保障文本可见性。 -
错误处理：网络失败或 CORS 问题会导致
fontFace.load()拒绝 Promise，务必try/catch或.catch()处理。 -
性能优化：避免在每次渲染中重复调用
loadFonts；使用useMemo或单例缓存已加载字体。 -
兼容性：
FontFaceAPI 支持现代浏览器（Chrome 35+, Firefox 41+, Safari 10.1+），旧版需降级 fallback（如<link rel="stylesheet">）。 -
替代思路（非推荐）：若坚持 CSS 方案，可借助构建时插件（如
dotenv-webpack+sass-resources-loader）将环境变量注入 SCSS，但丧失运行时灵活性，且增加构建复杂度。
通过以上方式，你不仅能实现真正的“环境驱动字体路径”，还能获得细粒度控制、按需加载、错误隔离和良好的可维护性——这才是现代 React 应用中字体管理的专业实践。
