ViteJS（原生React）环境本地托管字体不生效如何解决

核心问题排查&修复步骤 #

• 第一步：修正@font-face引用路径
  Vite 中public目录下的静态资源会被直接映射到站点根路径，引用时不需要带public前缀，直接以/开头写绝对路径即可。你当前的字体存放在public/fonts/montserrate-regular.woff，对应正确的@font-face写法如下：

  @font-face {
    /* 自定义字体名，后续引用要和这个值完全一致 */
    font-family: 'Montserrate';
    /* 注意路径直接从/fonts开头，不要加public层级 */
    src: url('/fonts/montserrate-regular.woff') format('woff');
    font-weight: 400;
    font-style: normal;
    /* 可选：优化字体加载体验，避免文字不可见的闪烁问题 */
    font-display: swap;
  }
  

  高频踩坑提醒：先核对本地字体文件名拼写，你写的montserrate比常规Montserrat字体名多了一个末尾的e，文件名和url里的拼写必须完全一致，否则会报404错误。

• 第二步：确认CSS文件被正确加载
  检查项目入口文件main.jsx/main.tsx中是否全局引入了index.css，确保引入代码存在：

  import React from 'react'
  import ReactDOM from 'react-dom/client'
  import './index.css' // 这行不能遗漏
  import App from './App'
  
  ReactDOM.createRoot(document.getElementById('root')).render(
    <React.StrictMode>
      <App />
    </React.StrictMode>,
  )
  

• 第三步：确认字体被正确应用到元素
  声明@font-face后不会自动全局生效，需要给目标元素指定对应font-family，比如要全局生效可以加全局样式：

  body {
    /* 字体名要和@font-face里声明的完全一致，后面加系统兜底字体 */
    font-family: 'Montserrate', sans-serif;
  }
  

更稳妥的字体引入方案（推荐） #

不建议把字体放在public目录，可以把字体文件移动到src/assets/fonts/目录下，在CSS中用相对路径引入，Vite构建时会自动校验文件是否存在、处理资源路径，避免路径写错导致的上线后404问题：

/* 假设index.css在src根目录，对应路径写法如下 */
@font-face {
  font-family: 'Montserrate';
  src: url('./assets/fonts/montserrate-regular.woff') format('woff');
  font-weight: 400;
  font-style: normal;
  font-display: swap;
}

快速排查技巧 #

打开浏览器开发者工具，切换到「网络」面板，筛选「字体」类型后刷新页面：

• 如果字体请求状态为404：优先排查路径拼写、文件名拼写错误
• 如果请求状态为200但字体不生效：检查font-family名称声明和引用是否一致、format值是否和字体实际格式匹配

内容的提问来源于stack exchange，提问作者Cesar Gomez