NX Monorepo下配置Emotion全局主题类型支持libs目录

DevOps 小满

2026-8-30

问题根因

当前@emotion/react的主题类型扩展声明写在apps/web单应用目录下，TypeScript编译libs目录的共享代码时，不会主动加载web应用目录内的类型声明文件，因此会出现运行时可拿到正确主题值、但TS类型检查识别不到自定义字段的问题。

修复步骤

把Emotion全局类型声明移到共享库目录，不要放在单个应用下。直接在libs/shared-ui/theming路径下新建emotion.d.ts文件，写入类型扩展代码，注意这里直接从共享库内部路径引入ThemeType，避免包名自引用导致的循环问题：

import '@emotion/react';
import type { ThemeType } from './theme-type'; // 替换为项目内ThemeType实际的相对路径

declare module '@emotion/react' {
  export interface Theme extends ThemeType {}
}

// 如果mobile端用@emotion/native，追加下面这段即可对齐双端类型
import '@emotion/native';
declare module '@emotion/native' {
  export interface Theme extends ThemeType {}
}

修改仓库根目录的tsconfig.base.json，让所有apps、libs下的TS检查都能加载到这份全局声明。Nx下所有子项目的tsconfig默认都会继承这份基础配置，在这里配置一次即可全仓生效：

{
  "compilerOptions": {
    // 原有其他配置保持不变
  },
  "include": [
    // 原有include项保留，追加下面这行
    "libs/shared-ui/theming/emotion.d.ts"
  ]
}

删除之前散落在apps/web、apps/mobile目录下重复编写的Emotion主题声明代码，避免重复定义导致的类型冲突。
配置完成后如果编辑器还显示类型错误，直接重启TypeScript服务即可：VSCode下按快捷键Ctrl+Shift+P（Mac为Cmd+Shift+P），调出命令面板选择TypeScript: Restart TS Server，类型会立刻正常识别。