Chakra UI主题自定义字体无法在Heading组件渲染的问题排查

核心问题原因 #

1. 字体名称不匹配：@font-face 中声明的 font-family 名称必须和主题配置里的 fonts.heading 完全一致（包括引号、空格），否则Chakra无法关联到自定义字体，会直接 fallback 到系统默认字体。
2. 字体加载时机错误：如果字体样式注入晚于ChakraProvider初始化，Chakra生成CSS变量（--chakra-fonts-heading）时还没读取到自定义字体，导致变量值仍为默认。
3. Heading组件未显式继承主题字体：部分场景下，Chakra的Heading组件默认配置可能因主题扩展逻辑被覆盖，需要显式指定其字体来源为主题的heading字体。

具体修复步骤 #

1. 确保@font-face配置正确

在src/theme/Fonts.js中，严格匹配字体名称：

import { Global } from '@emotion/react';

export const Fonts = () => (
  <Global
    styles={`
      @font-face {
        font-family: 'Foo Bar'; // 必须和theme里的字体名完全一致
        src: url('./fonts/Foo-Bar.woff2') format('woff2'); // 注意路径是否正确
        font-weight: normal;
        font-style: normal;
        font-display: swap; // 优化加载体验
      }
    `}
  />
);

2. 正确配置主题并显式绑定Heading字体

在src/theme/index.js中，扩展主题时显式指定Heading组件的字体：

import { extendTheme } from '@chakra-ui/react';

const theme = extendTheme({
  fonts: {
    heading: "'Foo Bar', sans-serif", // 和@font-face的font-family完全匹配
    body: "'System UI', sans-serif",
  },
  // 显式配置Heading组件，确保继承主题字体
  components: {
    Heading: {
      baseStyle: {
        fontFamily: 'heading', // 直接引用主题中定义的heading字体变量
      },
    },
  },
});

export default theme;

3. 调整RootWrapper的加载顺序

确保Fonts组件在ChakraProvider内部加载，保证字体样式先于Chakra的组件样式生效：

import { ChakraProvider } from '@chakra-ui/react';
import theme from './theme';
import { Fonts } from './theme/Fonts';

export const RootWrapper = ({ children }) => (
  <ChakraProvider theme={theme}>
    <Fonts />
    {children}
  </ChakraProvider>
);

验证方法 #

• 打开浏览器开发者工具，查看任意Heading元素的font-family属性，确认'Foo Bar'排在第一位；
• 检查Sources面板，确认Foo-Bar.woff2已成功加载；
• 查看:root元素的CSS变量，确认--chakra-fonts-heading的值为'Foo Bar', sans-serif。

内容的提问来源于stack exchange，提问作者GʀᴜᴍᴘʏCᴀᴛ