拆分MUI主题至独立文件时遇TypeScript类型错误的解决方法

问题背景 #

Next.js项目中，src/theme/index.ts里直接编写MUI主题配置时代码可正常运行，但将按钮样式拆分到单独的buttonStyles.ts文件后，触发TypeScript类型不兼容错误，核心问题是自定义按钮variant的类型无法被正确识别。

原正常运行的index.ts代码 #

'use client'; // MUI适配Next.js SSR必需
import { createTheme } from '@mui/material/styles';
import { typography } from './typography';
import { palette } from './palette';

const theme = createTheme({
  palette,
  typography,
  components: {
    MuiButton: {
      styleOverrides: {
        root: {
          borderRadius: 8,
        }
      },
      variants: [
        {
          props: { variant: 'primary' },
          style: {
            backgroundColor: '#FFCB3C',
            color: '#1A334D',
            '&:hover': {
              backgroundColor: '#FFAA01',
            },
          },
        },
        {
          props: { variant: 'complementaryPrimary' },
          style: {
            backgroundColor: '#a09a88',
            color: '#ffffff',
            '&:hover': {
              backgroundColor: '#FFAA01',
            },
          },
        }
      ],
    }
  },
});

export default theme;

重构后的代码及错误 #

拆分出的buttonStyles.ts #

const buttonStyles = {
  MuiButton: {
    styleOverrides: {
      root: {
        borderRadius: 8,
      }
    },
    variants: [
      {
        props: { variant: 'primary' },
        style: {
          backgroundColor: '#FFCB3C',
          color: '#1A334D',
          '&:hover': {
            backgroundColor: '#FFAA01',
          },
        },
      },
      {
        props: { variant: 'complementaryPrimary' },
        style: {
          backgroundColor: '#a09a88',
          color: '#ffffff',
          '&:hover': {
            backgroundColor: '#FFAA01',
          },
        },
      }
    ],
  },
}

export default buttonStyles;

修改后的index.ts #

'use client'; // MUI适配Next.js SSR必需
import { createTheme } from '@mui/material/styles';
import buttonStyles from './buttonStyles';
import { typography } from './typography';
import { palette } from './palette';

const theme = createTheme({
  palette,
  typography,
  components: {
    ...buttonStyles,
  },
});

export default theme;

触发的TypeScript错误 #

Type '{ MuiButton: { styleOverrides: { root: { borderRadius: number; }; }; variants: { props: { variant: string; }; style: { backgroundColor: string; color: string; '&:hover': { backgroundColor: string; }; }; }[]; }; }' is not assignable to type 'Components<Omit<Theme, "components">>'.
  The types of 'MuiButton.variants' are incompatible between these types.
    Type '{ props: { variant: string; }; style: { backgroundColor: string; color: string; '&:hover': { backgroundColor: string; }; }; }[]' is not assignable to type '{ props: Partial<ButtonProps> | ((props: Partial<ButtonProps> & { ownerState: Partial<ButtonProps>; }) => boolean); style: Interpolation<...>; }[]'.
      Type '{ props: { variant: string; }; style: { backgroundColor: string; color: string; '&:hover': { backgroundColor: string; }; }; }' is not assignable to type '{ props: Partial<ButtonProps> | ((props: Partial<ButtonProps> & { ownerState: Partial<ButtonProps>; }) => boolean); style: Interpolation<...>; }'.
        Types of property 'props' are incompatible.
          Type '{ variant: string; }' is not assignable to type 'Partial<ButtonProps> | ((props: Partial<ButtonProps> & { ownerState: Partial<ButtonProps>; }) => boolean)'.
            Type '{ variant: string; }' is not assignable to type 'Partial<ButtonProps>'.
              Types of property 'variant' are incompatible.
                Type 'string' is not assignable to type 'OverridableStringUnion<"text" | "outlined" | "contained", ButtonPropsVariantOverrides> | undefined'.ts(2322)
(property) ThemeOptions.components?: Components<Omit<Theme, "components">> | undefined

尝试过直接展开buttonStyles.MuiButton、将buttonStyles赋值给MuiButton等方式，均因类型不匹配触发不同错误。

解决方案 #

问题核心是拆分后TypeScript丢失上下文，无法推断variant的正确类型（默认将其识别为宽泛的string，而非MUI要求的OverridableStringUnion），以下三种方法可解决：

方法1：用as const保留字面量类型 #

给variant值或整个对象添加as const，强制TypeScript保留字面量类型：

const buttonStyles = {
  MuiButton: {
    styleOverrides: {
      root: {
        borderRadius: 8,
      }
    },
    variants: [
      {
        props: { variant: 'primary' as const },
        style: {
          backgroundColor: '#FFCB3C',
          color: '#1A334D',
          '&:hover': {
            backgroundColor: '#FFAA01',
          },
        },
      },
      {
        props: { variant: 'complementaryPrimary' as const },
        style: {
          backgroundColor: '#a09a88',
          color: '#ffffff',
          '&:hover': {
            backgroundColor: '#FFAA01',
          },
        },
      }
    ],
  },
} as const;

export default buttonStyles;

方法2：手动指定MUI组件类型 #

导入MUI的Components类型，给buttonStyles指定正确的类型约束：

import type { Components, Theme } from '@mui/material/styles';

const buttonStyles: Components<Omit<Theme, "components">> = {
  MuiButton: {
    styleOverrides: {
      root: {
        borderRadius: 8,
      }
    },
    variants: [
      {
        props: { variant: 'primary' },
        style: {
          backgroundColor: '#FFCB3C',
          color: '#1A334D',
          '&:hover': {
            backgroundColor: '#FFAA01',
          },
        },
      },
      {
        props: { variant: 'complementaryPrimary' },
        style: {
          backgroundColor: '#a09a88',
          color: '#ffffff',
          '&:hover': {
            backgroundColor: '#FFAA01',
          },
        },
      }
    ],
  },
};

export default buttonStyles;

方法3：针对MuiButton内部配置的类型修正 #

如果拆分时只保留MuiButton的内部配置（不含MuiButton键），需指定对应的类型：

import type { ButtonProps, Theme } from '@mui/material/styles';
import type { OverridesStyleRules } from '@mui/material/styles/overrides';

const buttonStyles: {
  styleOverrides?: Partial<OverridesStyleRules<keyof typeof import('@mui/material/Button/Button').defaultClasses, "MuiButton", Theme>>;
  variants?: {
    props: Partial<ButtonProps>;
    style: React.CSSProperties;
  }[];
} = {
  styleOverrides: {
    root: {
      borderRadius: 8,
    }
  },
  variants: [
    {
      props: { variant: 'primary' as const },
      style: {
        backgroundColor: '#FFCB3C',
        color: '#1A334D',
        '&:hover': {
          backgroundColor: '#FFAA01',
        },
      },
    },
    {
      props: { variant: 'complementaryPrimary' as const },
      style: {
        backgroundColor: '#a09a88',
        color: '#ffffff',
        '&:hover': {
          backgroundColor: '#FFAA01',
        },
      },
    }
  ],
};

export default buttonStyles;

对应的index.ts使用方式：

'use client';
import { createTheme } from '@mui/material/styles';
import buttonStyles from './buttonStyles';
import { typography } from './typography';
import { palette } from './palette';

const theme = createTheme({
  palette,
  typography,
  components: {
    MuiButton: buttonStyles,
  },
});

export default theme;

原理说明 #

当代码写在createTheme参数内部时，TypeScript可通过上下文自动推断variant的正确类型（包含自定义扩展）；拆分到单独文件后，上下文丢失，TypeScript会将variant识别为普通string，导致与MUI要求的类型不兼容。通过as const或手动指定类型，可让TypeScript识别出这是符合要求的variant值。

内容的提问来源于stack exchange，提问作者jose.gp