unbuild项目中的默认导出类型声明问题解析

在JavaScript/TypeScript生态系统中，模块系统的兼容性一直是个重要话题。最近在unbuild项目中发现了一个关于CommonJS模块默认导出类型声明的问题，这个问题会影响TypeScript用户的使用体验。

问题背景

当使用unbuild构建一个仅包含默认导出的模块时，构建工具会生成两种输出：运行时文件(.cjs)和类型声明文件(.d.cts)。在当前的实现中，运行时文件能够正确输出CommonJS风格的默认导出，但对应的类型声明文件却使用了ES模块风格的导出语法，这会导致类型检查与实际运行时行为不一致的问题。

具体表现为：

• 源代码使用export default function add() {...}
• 运行时输出正确的module.exports = add
• 但类型声明文件输出错误的export { add as default }

问题影响

这种不一致会导致TypeScript用户在导入该模块时遇到类型检查错误。虽然代码在运行时能正常工作，但TypeScript会认为这是一个ES模块的默认导出，而实际上它是一个CommonJS的默认导出。这种差异会导致工具链（如IDE和类型检查工具）给出错误的提示。

技术分析

在CommonJS模块系统中，默认导出应该使用export =语法来表示，这是TypeScript专门为CommonJS模块设计的类型声明语法。而ES模块的export { add as default }语法在CommonJS上下文中并不等价，它实际上会创建一个名为"default"的命名导出。

正确的类型声明应该是：

declare function add(): number;
export = add;

解决方案

参考其他构建工具(如tsup)的做法，可以在生成类型声明文件后，对内容进行后处理：

1. 检测是否只有默认导出
2. 将export { X as default }替换为export = X
3. 确保其他导出形式不受影响

这种处理方式既保持了与现有代码的兼容性，又解决了类型声明准确性的问题。

最佳实践建议

对于库开发者，建议：

1. 明确模块系统目标(ESM或CJS)
2. 定期使用类型检查工具验证生成的声明文件
3. 在构建配置中显式指定模块格式
4. 考虑为不同模块系统提供不同的构建输出

对于unbuild用户，如果遇到类似问题，可以暂时手动修改生成的声明文件，或者等待官方修复后升级版本。

这个问题的修复将提升unbuild在TypeScript生态中的兼容性和可靠性，特别是对于那些需要同时支持ESM和CJS的库项目。