Vite+React集成本地自定义字体时遇到文件识别问题

核心思路 #

Vite默认支持处理ttf/woff/woff2等字体文件，无需额外配置插件，但必须通过@font-face在全局样式中完成字体定义后再调用，不能直接在JS中引用字体文件本身。

步骤1：确认字体文件位置 #

将自定义字体文件（比如SourceSansPro-Light.ttf）放在项目的src/assets/fonts/目录下，确保路径层级准确。

步骤2：在全局样式中定义并使用字体 #

方式一：用纯CSS文件管理全局样式

在项目的全局CSS文件（如global.css）中添加@font-face规则，直接引用字体路径：

@font-face {
  font-family: 'SourceSansPro-Light'; /* 自定义字体名称，后续调用用这个标识 */
  src: url('../assets/fonts/SourceSansPro-Light.ttf') format('truetype');
  font-weight: 300;
  font-style: normal;
  font-display: swap; /* 优化加载体验，避免无样式文本闪烁 */
}

/* 全局应用该字体 */
body {
  font-family: 'SourceSansPro-Light', sans-serif;
}

最后在main.jsx中导入这个CSS文件：

import './global.css';

方式二：用Styled Components的GlobalStyle

如果用styled-components管理全局样式，先导入字体文件（Vite会返回打包后的文件URL），再在createGlobalStyle中定义：

import { createGlobalStyle } from 'styled-components';
import fontLight from './assets/fonts/SourceSansPro-Light.ttf';

const GlobalStyles = createGlobalStyle`
  @font-face {
    font-family: 'SourceSansPro-Light';
    src: url(${fontLight}) format('truetype');
    font-weight: 300;
    font-style: normal;
    font-display: swap;
  }

  * {
    box-sizing: border-box;
    margin: 0;
    padding: 0;
  }

  body {
    font-family: 'SourceSansPro-Light', sans-serif;
  }
`;

export default GlobalStyles;

然后在根组件中渲染GlobalStyles：

import GlobalStyles from './GlobalStyles';

function App() {
  return (
    <>
      <GlobalStyles />
      {/* 其他业务组件 */}
    </>
  );
}

步骤3：验证字体生效 #

打开浏览器开发者工具的Elements面板，查看元素的font-family属性是否正确应用，或在Computed标签中确认字体来源。

你之前遇到问题的原因 #

直接导入字体文件后，不能直接在React组件中使用，必须通过CSS的@font-face规则将文件路径关联到自定义字体名称，再在样式中调用这个名称。Vite会自动处理字体文件的打包、路径转换，无需额外配置。

内容的提问来源于stack exchange，提问作者Rahber Hussain