UnoCSS 在 SvelteKit 项目中的 TypeScript 模块解析问题解析

问题背景

在使用 UnoCSS 0.58.3 版本与 SvelteKit 项目结合时，当 TypeScript 配置中设置了 "module": "NodeNext" 和 "moduleResolution": "NodeNext" 选项时，会出现调用 UnoCSS() 函数时的类型错误提示。这个错误表明 TypeScript 无法识别 UnoCSS 模块的可调用签名。

技术分析

模块系统兼容性问题

这个问题本质上源于 UnoCSS 当前版本采用的是 CommonJS (CJS) 和 ECMAScript Modules (ESM) 双模式导出。当项目配置为纯 ESM 模式（使用 NodeNext 模块解析）时，TypeScript 的类型系统无法正确识别 UnoCSS 的导出结构。

具体表现

在代码中尝试这样导入时：

import UnoCSS from 'unocss/vite';

TypeScript 会报错：

This expression is not callable.
Type 'typeof import(".../node_modules/unocss/dist/vite")' has no call signatures.ts(2349)

深层原因

UnoCSS 的导出方式采用了混合模式：

export { type CompileClassOptions, transformerCompileClass as default };

这种导出方式在纯 ESM 环境下使用时，需要以 .default 的形式访问导出内容，这与传统的直接调用方式产生了冲突。

解决方案

临时解决方案

1. 使用 Bundler 模块解析：在 SvelteKit 2.0 中，可以将 TypeScript 配置改为使用 "moduleResolution": "Bundler"，这是新的默认值，能更好地处理模块解析问题。

2. 显式调用 .default：

import UnoCSS from 'unocss/vite';
UnoCSS.default(); // 显式调用 default

长期解决方案

UnoCSS 团队已经在处理这个问题，通过 PR #3380 正在将 UnoCSS 迁移到 ESM 优先/唯一的包导出方式。这将从根本上解决模块系统兼容性问题。

最佳实践建议

对于 SvelteKit 项目开发者：

1. 如果项目不急于升级，可以暂时保持原有模块系统配置
2. 新项目建议直接使用 SvelteKit 2.0 的默认配置
3. 关注 UnoCSS 的版本更新，特别是 ESM 迁移完成后的问题修复版本

总结

这个问题是前端生态从 CommonJS 向 ESM 过渡期间常见的兼容性问题。UnoCSS 团队已经意识到并正在解决这个问题。开发者可以根据项目实际情况选择临时解决方案或等待官方修复。理解模块系统的差异和兼容性问题，有助于开发者更好地处理类似的技术挑战。