unplugin-auto-import 在 TypeScript ESM 环境下的类型导入问题解析

问题背景

在使用 unplugin-auto-import 插件时，开发者可能会遇到一个与 TypeScript ESM 模块导入相关的特殊问题。当尝试同时使用某个模块作为函数/类导入和类型导入时，会出现类型系统冲突。这种情况在使用 Cesium 这类同时提供类和类型定义的库时尤为明显。

典型问题场景

在正常的 ESM 导入方式下，我们可以这样编写代码而不会出现问题：

import { Cartesian4 } from 'cesium'

export function mylib5(): Cartesian4 {
    return new Cartesian4(0, 0, 0, 0)
}

然而，当使用 unplugin-auto-import 自动导入时，同样的代码结构会导致类型系统报错：

// 配置了自动导入 { cesium: ['Color'] }

export function mylib6(): Color {
    return new Color(0, 0, 0, 0)
}

上述代码会产生两个类型错误：

1. 'Color' refers to a value, but is being used as a type here. Did you mean 'typeof Color'?
2. Return type of exported function has or is using private name 'Color'.

问题根源分析

这个问题的核心在于 TypeScript 的类型系统和 JavaScript 运行时之间的差异。当使用自动导入时：

1. 自动导入只处理了值的导入（即可以实例化的类或可调用的函数），但没有正确处理类型导入
2. 当函数有显式返回类型注解时，TypeScript 需要能够访问该类型的定义
3. 在声明文件生成（declaration: true）的场景下，类型系统对类型的可见性要求更加严格

解决方案探索

方案一：分离值和类型导入

尝试通过配置分别导入值和类型：

// autoImport 配置
imports: [
  { cesium: ['Cartesian3'] },
  { 
    from: 'cesium',
    type: true,
    imports: ['Cartesian3']
  }
]

但这会导致新的错误：

1. Return type of exported function has or is using private name 'Cartesian3'
2. 'Cartesian3' cannot be used as a value because it was exported using 'export type'

方案二：类型导入重命名

尝试为类型导入使用不同的名称：

// autoImport 配置
imports: [
  { cesium: ['Cartesian2'] },
  { 
    from: 'cesium',
    type: true,
    imports: [['Cartesian2', 'TCartesian']]
  }
]

这解决了命名冲突，但在 declaration: true 的配置下仍会报 private name 错误。

最终解决方案

经过深入研究发现，问题的关键在于 TypeScript 的 declaration 编译选项。当该选项设置为 true 时，TypeScript 会严格检查类型定义的可见性。解决方案是：

1. 确保类型导入和值导入都正确配置
2. 为类型导入使用不同的名称以避免冲突
3. 调整 tsconfig.json 中的相关配置

正确的配置方式如下：

imports: [
  { cesium: ['Cartesian2'] },
  { 
    from: 'cesium',
    type: true,
    imports: [['Cartesian2', 'TCartesian']]
  }
]

配合适当的 tsconfig 设置，这种模式可以正常工作。

最佳实践建议

1. 对于同时需要作为值和类型使用的导入，始终配置双重导入（值和类型分开）
2. 为类型导入使用明确的前缀（如 T）以避免命名冲突
3. 在库开发时，注意 declaration 选项的影响
4. 考虑在团队中建立统一的自动导入命名规范

通过这种方式，开发者可以充分利用 unplugin-auto-import 的便利性，同时保持类型系统的完整性和正确性。