Webpack 5加载本地自定义字体不生效如何解决

核心原因 #

Webpack 5 已内置原生静态资源处理能力，url-loader、file-loader 已被官方标记为废弃方案，在Webpack 5环境下继续使用这两个loader处理字体文件，会出现资源解析错乱：所有不同的字体文件被错误打包为同一份内容，这就是无论指定哪个字重的Inter字体，最终加载到的都是同一份错误衬线字体、浏览器识别失败回退到Arial的根本原因。

修复步骤 #

• 替换废弃的loader配置
  删除原有配置中针对woff/woff2/ttf等字体后缀的url-loader/file-loader规则，改用Webpack 5内置的Asset Modules处理字体资源，参考配置如下：

  module.exports = {
    // ... 其余原有配置保持不变
    module: {
      rules: [
        // ... 其余原有loader规则保持不变
        {
          test: /\.(woff|woff2|ttf|otf|eot)$/,
          type: 'asset/resource',
          generator: {
            // 自定义构建后字体的输出路径与命名，避免随机文件名导致的资源混淆
            filename: 'fonts/[name].[hash:8][ext]'
          }
        }
      ]
    }
  }
  

• 校验字体声明正确性
  现有SCSS中的@font-face写法本身没有错误，ttf格式对应format("truetype")的声明是匹配的。如果追求更好的加载性能，建议优先使用woff2格式字体，相比ttf体积可缩小30%以上，对应格式声明改为format("woff2")即可。
• 确认样式引入顺序
  检查全局SCSS文件的引入位置，必须保证写了@font-face声明的样式文件在项目入口的最顶部引入，确保字体规则早于所有业务样式加载，不会被后续样式覆盖。
• 清除缓存重新构建
  删除项目下的node_modules/.cache缓存目录，重启开发服务或重新执行生产构建命令，强制重新打包所有静态资源，避免旧的错误构建缓存干扰结果。

额外排查项 #

如果以上操作完成后字体仍未正常生效，可逐一排查两个高频问题：

• 本地字体源文件损坏：直接双击打开src/assets/fonts/目录下的ttf文件，通过系统字体预览功能确认文件本身是正常的Inter无衬线字体，排除字体下载错误、源文件损坏的问题。
• 浏览器插件干扰：部分字体美化、广告拦截类插件会强制覆写页面字体配置，可打开浏览器无痕模式、禁用所有扩展后重新访问页面验证。

内容的提问来源于stack exchange，提问作者Seth Lutske