注释d.ts内createTheme导入后MUI成员导入报错问题排查

这个异常是TypeScript对「全局脚本」和「模块」的类型处理规则差异导致的，和MUI本身逻辑无关。

核心规则说明 #

TypeScript判定文件类型的标准非常明确：

• 只要文件顶层存在import/export语句，就会被识别为ES模块，模块内的declare module 'xxx'语法会被识别为模块扩充，会和目标模块的原有类型做合并，不会覆盖原有类型
• 如果文件顶层没有任何import/export语句，就会被识别为全局脚本，脚本内的declare module 'xxx'语法会被识别为模块的完整类型定义，会直接替换掉目标模块的所有原有类型

对应场景的逻辑拆解 #

注释导入后的.d.ts文件报错原因 #

当你注释掉createTheme的导入语句后，expanded-theme.d.ts文件里没有任何顶层import/export，被TS识别为全局脚本。此时你写的

declare module '@mui/material/styles' { /* ... */ }
declare module "@mui/material" { /* ... */ }

会直接替换掉MUI官方提供的@mui/material/styles、@mui/material两个包的全部类型定义，而不是在官方类型基础上追加自定义的play、moreInfo调色板属性。官方导出的createTheme、Button、FormControl等成员的类型全部被覆盖丢失，所以会报「模块没有对应导出成员」的错误。

之前保留createTheme导入时不报错，就是因为顶层import语句让文件被识别为模块，类型扩充逻辑正常生效。

改.ts加export {}后恢复正常的原因 #

export {}是显式的顶层导出语句，哪怕文件里没有其他导入导出，只要存在这行代码，TS就会把文件识别为ES模块。此时文件内的declare module会走模块扩充逻辑，和MUI原有类型合并，不会覆盖官方导出的成员类型，所以报错消失。 #

最佳实践 #

编写MUI（或其他第三方库）的类型扩充代码时，无论使用.ts还是.d.ts扩展名，建议都在文件末尾固定添加一行export {}，不需要额外导入库成员也能保证模块扩充逻辑正常生效，避免出现类型被意外覆盖的问题。

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