TypeScript：类型声明文件导入实现文件枚举的循环依赖问题及解决

现有实现文件 module.ts 和类型声明文件 module.d.ts 代码如下：

// module.ts
import type { ConfigI } from './module.d.ts';

export enum ConfigType {
  Simple,
  Complex
}

function performTask(config: ConfigI) {
  if (config.type === ConfigType.Simple) {
    // 执行对应逻辑
  }
}

// module.d.ts
import { ConfigType } from './module.ts';

export interface ConfigI {
  type: ConfigType;
}

当前存在两个核心问题：一是实现文件与声明文件形成循环依赖，二是TypeScript不允许在声明文件中导入带有运行时值的枚举（枚举包含可执行代码，不属于纯类型范畴）。

你提到的一种潜在方案是在声明文件中用字面量联合类型定义ConfigType：

// module.d.ts
export type ConfigType = 
  0 | // Simple
  1;  // Complex

export interface ConfigI {
  type: ConfigType;
}

但该方案存在明显缺陷：

• 可读性差：config.type === 0远不如config.type === ConfigType.Simple语义清晰
• 扩展性弱：后续若切换为字符串枚举，需修改大量硬编码字面量；若用字符串字面量，又会丢失数字枚举的数值特性

推荐重构方案 #

我们可以通过类型定义与运行时枚举分离对齐的方式，既解决循环依赖，又保留枚举的可读性与特性：

方案一：类型与运行时完全分离

步骤1：声明文件定义纯类型

在module.d.ts中直接定义枚举对应的字面量联合类型，无需导入任何运行时内容：

// module.d.ts
export type ConfigType = 0 | 1;

export interface ConfigI {
  type: ConfigType;
}

步骤2：实现文件对齐枚举与类型

在module.ts中导出的枚举，确保其值与声明文件的字面量完全匹配，并用satisfies语法（TypeScript 4.9+）做类型校验：

// module.ts
import type { ConfigI, ConfigType } from './module.d.ts';

// 用satisfies确保枚举值严格匹配声明的类型
export enum ConfigTypeEnum {
  Simple = 0,
  Complex = 1
} satisfies Record<string, ConfigType>;

// 可选：导出与声明文件同名的类型别名，方便外部统一引用
export type ConfigType = import('./module.d.ts').ConfigType;

function performTask(config: ConfigI) {
  if (config.type === ConfigTypeEnum.Simple) {
    // 执行逻辑
  }
}

该方案优势：

• 彻底消除循环依赖：声明文件不再依赖任何运行时代码
• 保留语义可读性：代码中依然使用ConfigTypeEnum.Simple这类直观的枚举值
• 类型安全：通过satisfies确保枚举值与声明类型完全对齐，避免不一致
• 灵活性强：后续修改枚举类型（如切换为字符串），只需同步修改声明文件和实现文件的枚举值即可

方案二：合并类型与枚举导出（适用于对外暴露枚举的场景）

如果需要对外提供统一的枚举类型和运行时值，可以将类型提取与声明文件导入结合：

// module.ts
// 定义并导出运行时枚举
export enum ConfigType {
  Simple = 0,
  Complex = 1
}

// 提取枚举的类型，用于对外暴露纯类型
export type ConfigType = typeof ConfigType[keyof typeof ConfigType];

import type { ConfigI } from './module.d.ts';

function performTask(config: ConfigI) {
  if (config.type === ConfigType.Simple) {
    // 执行逻辑
  }
}

// module.d.ts
// 仅导入枚举的类型，而非整个运行时枚举
import type { ConfigType } from './module.ts';

export interface ConfigI {
  type: ConfigType;
}

该方案核心是利用typeof ConfigType[keyof typeof ConfigType]提取枚举的字面量类型，声明文件仅导入纯类型，避免了运行时依赖，同时保留了枚举的统一对外暴露方式。

内容的提问来源于stack exchange，提问作者Ansis Spruģevics