在Express与TypeScript项目中解决Lucia库的ESM兼容性问题

问题背景

在使用Lucia身份验证库构建Express与TypeScript项目时，开发者可能会遇到ES模块(ESM)与CommonJS模块系统之间的兼容性问题。特别是在使用ts-node运行TypeScript文件时，会出现ERR_REQUIRE_ESM错误，提示require()无法直接加载ES模块。

错误现象分析

当开发者尝试通过以下方式导入Lucia库时：

import { Lucia } from 'lucia';

系统会抛出错误，指出require()不支持加载ES模块，建议改用动态import()语法。这是因为Lucia库采用了现代的ES模块格式，而ts-node默认使用CommonJS模块系统。

解决方案

1. 使用tsx替代ts-node

推荐使用tsx作为TypeScript运行时替代ts-node。tsx对ES模块有更好的支持，能够无缝处理现代JavaScript模块系统。

安装tsx：

npm install -g tsx

然后使用以下命令运行项目：

tsx src/index.ts

2. 类型声明处理

当将类型声明移至.d.ts文件时，可能会遇到类型推断问题。确保在类型声明中正确定义了用户属性：

// lucia.d.ts
declare module 'lucia' {
    interface Register {
        Lucia: typeof lucia;
        DatabaseUserAttributes: {
            name: string;
            username: string;
            email: string;
        };
    }
}

3. 配置调整

确保项目的tsconfig.json中包含适当的模块设置：

{
  "compilerOptions": {
    "module": "ESNext",
    "moduleResolution": "node",
    "esModuleInterop": true
  }
}

最佳实践建议

1. 对于新项目，建议从一开始就采用ES模块系统
2. 保持依赖项版本更新，确保模块兼容性
3. 考虑使用更现代的运行时环境如tsx或直接使用Node.js的ES模块支持
4. 在团队协作项目中，统一开发环境的配置和工具链

通过以上方法，开发者可以顺利在Express与TypeScript项目中使用Lucia库，避免模块系统兼容性问题，同时获得完整的类型安全支持。