TailwindCSS v3.1.6自定义字体无法生效问题排查

在项目中使用自定义字体时无法生效，以下是配置代码：

tailwind.config.cjs:

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: ["./src/**/*.{js,ts,jsx,tsx}"],
  theme: {
    extend: {
      fontFamily: {
        heliosbold: ["HeliosBold", "sans-serif"],
        helios: ["Helios", "sans-serif"],
      },
    },
  },
  plugins: [],
};

global.css:

@font-face {
    font-family: HeliosBold;
    src: url('/fonts/heliosBold.woff2') format('woff2');
    font-weight: 400;
    font-display: swap;
    font-style: normal;
}


@font-face {
    font-family: Helios;
    src: url('/fonts/helios.woff2') format('woff2');
    font-weight: 400;
    font-display: swap;
    font-style: normal;
}

@tailwind base;
@tailwind components;
@tailwind utilities;

这段代码在TailwindCSS v3.0.24中可正常运行，但升级到v3.1.6后失效，请问版本有何变更或操作有误？

核心版本变更 #

Tailwind CSS v3.1+ 对自定义字体的字重匹配逻辑做了严格校验：

• v3.0及更早版本会忽略font-weight不匹配的情况，强制应用指定字体；
• v3.1+ 要求@font-face中定义的font-weight必须与Tailwind工具类的字重完全对应，否则会直接 fallback 到后备字体（比如sans-serif）。

修正步骤 #

1. 调整@font-face的字重定义
   把粗体字体的font-weight设为700（对应Tailwind的font-bold类），并将常规体和粗体归到同一个字体族下：

   @font-face {
       font-family: Helios;
       src: url('/fonts/helios.woff2') format('woff2');
       font-weight: 400;
       font-display: swap;
       font-style: normal;
   }
   
   @font-face {
       font-family: Helios;
       src: url('/fonts/heliosBold.woff2') format('woff2');
       font-weight: 700;
       font-display: swap;
       font-style: normal;
   }
   
   @tailwind base;
   @tailwind components;
   @tailwind utilities;
   

2. 简化Tailwind配置
   不需要单独定义heliosbold字体族，通过字重区分即可：

   /** @type {import('tailwindcss').Config} */
   module.exports = {
     content: ["./src/**/*.{js,ts,jsx,tsx}"],
     theme: {
       extend: {
         fontFamily: {
           helios: ["Helios", "sans-serif"],
         },
       },
     },
     plugins: [],
   };
   

3. 正确使用字体类

   • 常规体：font-helios（默认字重400，可搭配font-normal）
   • 粗体：font-helios font-bold

额外检查点 #

• 打开浏览器开发者工具的Network面板，确认字体文件是否成功加载，路径是否正确；
• 确保@font-face定义在@tailwind base之前，你的原配置顺序是正确的，无需调整。

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