如何配置MUI v5自定义font-family，实现全局组件统一生效？

解决方案 #

1. 先确认字体已正确引入 #

首先必须确保MetricHPEXS字体已通过@font-face正确注册，且字体文件路径可正常访问，示例配置如下（可放在全局CSS文件或主题配置中）：

@font-face {
  font-family: 'MetricHPEXS';
  src: url('/你的字体文件路径/MetricHPEXS-Regular.woff2') format('woff2');
  font-weight: 400;
  font-style: normal;
  font-display: swap;
}

可以先在Chrome开发者工具的网络面板检查是否有字体文件加载失败的404报错。

2. 简化主题配置，不需要为单个组件重复覆写字体 #

MUI v5所有组件默认会继承主题typography.fontFamily配置，不需要单独给MuiFormControl/MuiInput等组件逐一设置字体，正确的主题配置如下：

import { createTheme, TypographyOptions } from '@mui/material/styles';

const theme = createTheme({
  typography: {
    allVariants: MetricFontFaces,
    // 增加系统兜底字体，避免自定义字体加载失败时显示异常
    fontFamily: 'MetricHPEXS, system-ui, sans-serif'
  } as TypographyOptions,
  components: {
    // 全局样式统一覆写，确保所有元素都继承自定义字体
    MuiCssBaseline: {
      styleOverrides: {
        '*': {
          fontFamily: 'MetricHPEXS, system-ui, sans-serif !important'
        }
      }
    }
  }
});

3. 引用主题时增加CssBaseline组件 #

CssBaseline是MUI提供的全局样式重置组件，会自动将主题配置的字体应用到body及所有基础元素，是全局字体生效的必要依赖，Storybook引用调整如下：

import { CssBaseline, ThemeProvider, StyledEngineProvider } from '@mui/material';

<StyledEngineProvider injectFirst>
  <ThemeProvider theme={theme}>
    {/* 必须加CssBaseline */}
    <CssBaseline />
    {story()}
    <TextField value="sdasdasd" />
  </ThemeProvider>
</StyledEngineProvider>

补充检查项 #

如果依然不生效，可以打开开发者工具的元素面板，检查目标元素的font-family属性是否被Storybook自带的全局样式覆盖：

• 如果是优先级问题，可以保留主题配置里的!important强制生效
• 如果不需要自定义CSS覆盖MUI样式，可以移除injectFirst配置，让MUI样式优先级更高

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