解决PgTyped在CommonJS项目中模块解析错误的问题

问题背景

在使用PgTyped这个TypeScript数据库查询工具时，许多开发者遇到了一个常见的模块解析问题。当项目使用CommonJS模块系统时，TypeScript会报错提示无法用require导入ECMAScript模块。这个错误表面上看是模块系统不兼容的问题，但实际上与TypeScript的类型解析机制密切相关。

问题本质

这个问题的根源在于PgTyped项目在package.json中exports字段的类型声明配置不够完善。TypeScript在Node16模块解析模式下，会严格检查类型声明文件(.d.ts)的扩展名是否与导入的文件类型匹配。当项目使用CommonJS时，TypeScript期望看到.d.cts扩展名的类型声明文件，而PgTyped只提供了标准的.d.ts文件。

技术细节解析

在Node.js生态中，随着ES模块的普及，模块系统变得复杂起来。TypeScript为了准确处理不同模块系统下的类型检查，引入了对声明文件扩展名的特殊要求：

1. .d.ts - 传统的类型声明文件
2. .d.mts - 专门用于ES模块的类型声明
3. .d.cts - 专门用于CommonJS模块的类型声明

当项目配置了"moduleResolution": "node16"时，TypeScript会严格执行这些扩展名规范，确保类型系统与实际的模块系统一致。

解决方案

解决这个问题的方案是在PgTyped项目中：

1. 创建一个新的index.d.cts文件，内容与现有的index.d.ts完全相同
2. 修改package.json中的exports字段，为types字段添加条件导出：
   • import时使用.d.ts
   • require时使用.d.cts
   • 默认情况下使用.d.ts

这种配置方式完美解决了TypeScript在不同模块系统下的类型检查需求，同时保持了向后兼容性。

实际影响

这个问题主要影响以下场景的开发者：

• 使用CommonJS模块系统的Node.js项目
• 配置了严格模块解析选项的TypeScript项目
• 需要同时支持ES模块和CommonJS的库开发者

通过这个修复，PgTyped现在可以无缝工作在各类TypeScript项目中，无论开发者选择哪种模块系统。这大大提升了库的兼容性和开发者体验。

最佳实践建议

对于库开发者来说，这是一个很好的实践案例，展示了如何正确处理现代TypeScript项目中的模块解析问题。建议所有需要同时支持ES模块和CommonJS的TypeScript库都采用类似的解决方案：

1. 提供.d.ts和.d.cts两套类型声明文件
2. 在package.json中正确配置条件导出
3. 确保类型声明文件内容一致
4. 测试在不同模块系统下的表现

这种方案既符合TypeScript的最新规范，又能兼容各种使用场景，是处理模块系统兼容性的理想选择。