Node-postgres在ESM项目中的使用指南

ESM与CommonJS模块系统的兼容性问题

在现代JavaScript开发中，模块系统主要有两种标准：ESM(ECMAScript Modules)和CommonJS。随着Node.js对ESM的原生支持，越来越多的项目开始采用ESM作为默认模块系统。然而，当我们在ESM项目中需要使用基于CommonJS编写的库时，可能会遇到一些兼容性问题。

问题现象分析

在ESM项目中使用node-postgres(pg)库时，开发者可能会遇到模块导入错误。典型表现为当项目package.json中设置了"type": "module"时，尝试导入pg库会出现类似"require is not defined"的错误提示。

这是因为pg库的核心文件(default.js)采用了CommonJS规范编写，而ESM项目默认期望所有模块都遵循ESM规范。这种模块系统的不匹配导致了运行时的错误。

解决方案

方案一：使用动态导入

ESM提供了动态导入语法，可以异步加载CommonJS模块：

import('pg').then(({ Client }) => {
  // 使用Client
}).catch(err => console.error(err));

或者使用async/await：

async function connect() {
  const { Client } = await import('pg');
  // 使用Client
}

方案二：修改项目配置

如果项目允许，可以在package.json中添加以下配置来启用对CommonJS模块的兼容：

{
  "type": "module",
  "dependencies": {
    "pg": "^8.0.0"
  }
}

同时确保Node.js版本足够新(建议14+)，现代Node.js版本已经改进了对混合模块系统的支持。

方案三：使用中间适配层

创建一个适配文件(cjs-adapter.js)：

import { createRequire } from 'module';
const require = createRequire(import.meta.url);
const { Client } = require('pg');

export { Client };

然后在ESM模块中导入适配层：

import { Client } from './cjs-adapter.js';

最佳实践建议

1. 版本控制：确保使用的pg版本足够新，新版对ESM支持更好
2. 统一模块系统：如果可能，尽量统一项目中的模块系统规范
3. 错误处理：对模块导入添加适当的错误处理逻辑
4. 依赖检查：定期检查项目依赖，优先选择原生支持ESM的库

总结

在ESM项目中使用CommonJS模块(如node-postgres)是完全可行的，关键在于选择合适的兼容方案。随着Node.js生态的发展，模块系统间的界限正在逐渐模糊，但现阶段开发者仍需注意这种差异带来的潜在问题。通过上述方案，可以平滑地在ESM项目中使用强大的node-postgres库进行PostgreSQL数据库操作。