解决ESM项目导入CJS默认导出类时的TypeError问题

本文探讨在ESM（ECMAScript Modules）项目中导入CommonJS（CJS）模块的默认导出类时遇到的TypeError: TestClass is not a constructor问题。该问题源于ESM对CJS默认导出的特殊处理。文章将详细解释错误原因，并提供三种有效的解决方案：通过.default属性访问、统一模块格式，以及利用Node.js的createRequire函数，帮助开发者顺利解决跨模块格式的互操作性挑战。

引言：ESM与CJS的互操作性挑战

在Node.js生态系统中，ECMAScript Modules (ESM) 和 CommonJS (CJS) 是两种主流的模块系统。ESM以其现代化的语法和静态分析优势逐渐成为主流，而CJS则在Node.js早期版本中占据主导地位，大量现有库仍采用CJS格式。当一个使用ESM语法的项目（例如，在package.json中设置"type": "module"）尝试导入并实例化一个CJS模块中默认导出的类时，开发者可能会遇到运行时错误，例如TypeError: TestClass is not a constructor。这通常是由于ESM对CJS默认导出的特殊处理机制引起的。

问题剖析：为什么会出现“TestClass不是构造函数”？

当一个ESM模块使用import TestClass from "testpackage";语句从一个CJS模块导入默认导出时，Node.js的模块加载器会进行兼容性处理。CJS模块的默认导出（通常通过module.exports = SomeClass;或exports.default = SomeClass;实现）在ESM环境中不会被直接解析为构造函数本身。相反，ESM会将整个CJS模块视为一个对象，并将CJS的默认导出包装在该对象的default属性下。

考虑以下项目结构和代码片段，它们展示了导致TypeError的典型场景：

主项目配置 (myproject/package.json)

{
  "name": "myproject",
  "version": "1.0.0",
  "main": "dist/index.js",
  "scripts": {
    "build": "tsc",
    "start": "node dist/index.js"
  },
  "type": "module", // 明确指定为ESM项目
  "dependencies": {
    "testpackage": "^1.0.0",
    "typescript": "^5.0.4"
  }
}

主项目入口文件 (myproject/src/index.ts)

import TestClass from "testpackage"; // 尝试导入默认导出

new TestClass({ arg1: "Hello, World!" }); // 运行时抛出 TypeError

依赖包配置 (testpackage/package.json)

{
    "name": "testpackage",
    "version": "1.0.0",
    "description": "TestPackage",
    "main": "./dist/testFile.js",
    "exports": "./dist/testFile.js",
    "scripts": {
        "build": "tsc"
    },
    "files": ["dist"],
    "devDependencies": {
        "@types/node": "^20.2.5",
        "typescript": "^5.0.4"
    }
}

依赖包的CJS输出 (testpackage/dist/testFile.js)

"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
class TestClass {
    constructor({ arg1 }) {
        console.log(arg1);
    }
}
exports.default = TestClass; // CJS默认导出

在这种情况下，import TestClass from "testpackage";语句在ESM环境中加载testpackage时，TestClass变量实际上接收到的是一个对象 { default: TestClass }，而不是TestClass构造函数本身。因此，尝试 new TestClass(...) 会导致运行时错误 TypeError: TestClass is not a constructor。

值得注意的是，如果在主项目的tsconfig.json中设置"moduleResolution": "nodenext"，TypeScript编译器会在编译阶段就捕获到此问题，并报告TS2351: This expression is not constructable错误，这有助于在更早的阶段发现问题。

AI建筑知识问答

用人工智能ChatGPT帮你解答所有建筑问题

22

查看详情

解决方案一：显式访问默认导出

最直接的解决方案是理解ESM对CJS默认导出的处理方式，并通过访问导入模块的.default属性来获取实际的构造函数。

import TestModule from 'testpackage'; // 导入整个模块对象
const TestClass = TestModule.default; // 从模块对象中解构出默认导出

new TestClass({ arg1: "Hello, World!" });

在这个示例中，TestModule变量将接收到CJS模块导出的整个对象（即{ default: TestClass }）。通过.default属性，我们能够正确地引用到TestClass构造函数，从而解决TypeError。这种方法简单有效，适用于你确切知道CJS模块默认导出了一个类或函数的情况。

解决方案二：统一模块格式

从根本上解决互操作性问题的方法是确保项目及其所有依赖都使用相同的模块格式。这可以大大减少潜在的兼容性问题和理解成本。

1. 将CJS依赖转换为ESM（如果可行）：对于你拥有源代码或维护的内部库，将其从CJS转换为ESM是最佳实践。这通常涉及更新package.json的"type"字段，并调整导出/导入语法。然而，对于第三方库，这通常不现实。
2. 主项目切换回CJS（如果ESM不是强制需求）：如果你的主项目没有强烈的ESM需求，或者CJS依赖过多且难以替换，可以考虑将主项目也切换回CJS。这只需从package.json中移除"type": "module"字段即可。Node.js会默认将.js文件视为CJS模块。

在大型或复杂的项目中，保持模块格式的一致性是最佳实践，能有效减少潜在的兼容性问题和构建复杂性。

解决方案三：利用Node.js的createRequire函数

Node.js提供了一个createRequire函数，允许在ESM模块中创建一个CommonJS require函数。这使得ESM代码能够以CJS的方式加载CJS模块，从而绕过ESM对CJS默认导出的特殊包装机制。

import { createRequire } from 'module';
// 创建一个CJS的require函数，其路径上下文基于当前ESM文件的URL
const require = createRequire(import.meta.url); 

// 使用创建的require函数加载CJS模块
// 注意：即使使用require，如果CJS模块的默认导出是通过exports.default实现的，
// require('testpackage')仍会返回 { default: TestClass } 这样的对象。
const TestClass = require('testpackage').default; 

new TestClass({ arg1: "Hello, World!" });

这种方法适用于需要在ESM代码中显式地以CJS方式加载特定CJS模块的场景。它提供了一种混合模块格式的灵活性，但需要开发者清楚地理解require函数返回的对象结构。在我们的示例中，由于testpackage的CJS输出是exports.default = TestClass;，所以require('testpackage')会返回一个包含default属性的对象，因此仍然需要.default来访问实际的构造函数。

最佳实践与总结

为了避免ESM与CJS互操作性问题，并提升代码的健壮性，建议遵循以下最佳实践：

• 优先使用命名导出：在设计和编写自己的模块时，如果可能，优先使用命名导出（例如 export const MyClass = ...）而非默认导出。命名导出在ESM和CJS两种模块系统中表现更为一致，能够减少互操作时的复杂性。
• 理解TypeScript配置：熟悉tsconfig.json中moduleResolution选项的作用，尤其是"nodenext"模式。它能提供更严格的模块解析检查，有助于在编译阶段就发现潜在的运行时问题，而不是等到部署后才暴露。
• 关注依赖库的模块格式：在引入新的第三方库时，检查其package.json中的"type"字段或相关文档，了解其模块格式（ESM或CJS）。根据项目需求，选择提供ESM兼容版本的库，或准备采取相应的兼容措施。
• 选择合适的导入策略：根据CJS模块的具体导出方式（是module.exports = SomeClass;还是exports.default = SomeClass;），以及项目对ESM/CJS混合使用的接受程度，选择最合适的导入策略。

解决ESM与CJS互操作性问题的关键在于深入理解它们的模块解析机制差异，并根据具体场景选择最合适的导入和兼容策略。通过本文介绍的方法，开发者可以有效地应对这类TypeError，确保项目顺利运行。

以上就是解决ESM项目导入CJS默认导出类时的TypeError问题的详细内容，更多请关注php中文网其它相关文章！