unplugin-auto-import 在 TypeScript ESM 导入中的类型处理问题解析

问题背景

在使用 unplugin-auto-import 插件时，开发者可能会遇到一个典型问题：当尝试同时将一个模块导入作为函数调用和类型使用时，TypeScript 编译器会报错。这种情况在使用 Cesium 这类同时提供类和类型定义的库时尤为明显。

问题现象

正常情况下，通过 ESM 导入方式可以完美工作：

import { Cartesian4 } from 'cesium'

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

但当使用 unplugin-auto-import 时，会出现以下问题：

1. 类型与值冲突：TypeScript 会提示"'Color' refers to a value, but is being used as a type here"错误
2. 私有名称错误：当函数有返回类型声明时，会提示"Return type of exported function has or is using private name"错误
3. 类型导出冲突：当尝试单独导入类型时，会提示"'Cartesian3' cannot be used as a value because it was exported using 'export type'"

根本原因分析

这个问题的核心在于 TypeScript 的类型系统和 unplugin-auto-import 的自动导入机制之间的交互方式。当使用自动导入时：

1. 默认情况下，自动导入只处理值空间（value space）的导入，不处理类型空间（type space）
2. 当尝试将导入的值同时用作类型时，TypeScript 无法正确推断类型信息
3. 在生成声明文件（.d.ts）时，TypeScript 需要明确的类型信息，而自动导入的类型可能被视为"私有"

解决方案

经过深入研究和实验，发现以下配置可以解决这个问题：

// 在unplugin-auto-import配置中
imports: [
  { cesium: ['Cartesian2'] }, // 值导入
  { 
    from: 'cesium',
    type: true, // 明确指定为类型导入
    imports: [['Cartesian2', 'TCartesian']], // 使用别名避免命名冲突
  }
]

同时，需要在 tsconfig.json 中确保以下配置：

{
  "compilerOptions": {
    "declaration": true // 必须开启声明文件生成
  }
}

技术原理

1. 值空间与类型空间分离：TypeScript 中，类和类型存在于不同的命名空间。一个类名既可以在值空间中使用（通过 new 实例化），也可以在类型空间中使用（作为类型注解）

2. 自动导入的局限性：unplugin-auto-import 默认只处理值空间的导入，需要显式配置才能处理类型导入

3. 声明文件生成：当开启 declaration 选项时，TypeScript 会严格检查所有导出类型的可见性，确保它们都能在声明文件中正确表示

最佳实践建议

1. 对于同时需要作为值和类型使用的导入，建议采用值导入和类型导入分离的方式
2. 为类型导入使用特定前缀（如 T）或后缀（如 Type）可以增强代码可读性
3. 在库开发中，确保 tsconfig.json 中 declaration 选项设置为 true
4. 对于复杂的类型依赖，考虑在项目中维护专门的类型定义文件

总结

unplugin-auto-import 是一个强大的自动导入工具，但在处理 TypeScript 类型系统时需要特别注意值和类型的区分。通过合理的配置和遵循 TypeScript 的最佳实践，可以充分发挥自动导入的便利性，同时保持类型系统的完整性。理解 TypeScript 的值空间和类型空间概念是解决这类问题的关键。