解决ESM与CJS模块默认导出互操作性问题-js教程-PHP中文网

解决ESM与CJS模块默认导出互操作性问题

霞舞

发布： 2025-10-11 13:30:08

原创

743人浏览过

解决esm与cjs模块默认导出互操作性问题

当ESM项目尝试实例化一个CommonJS模块的默认导出类时，常会遇到TypeError: TestClass is not a constructor错误。这源于ESM对CJS默认导出的处理机制，它会将CJS的exports.default包装在一个default属性中。本文将深入探讨此问题的原因，并提供三种有效的解决方案：通过.default属性访问、统一模块格式，或使用Node.js的createRequire函数，以确保模块间的平滑互操作。

ESM与CJS默认导出互操作性概述

在现代JavaScript开发中，模块系统主要分为两种：CommonJS (CJS) 和 ECMAScript Modules (ESM)。Node.js环境同时支持这两种模块系统，但它们之间的互操作性，尤其是在默认导出方面，存在一些细微的差异，可能导致运行时错误。

当一个ESM项目（通过"type": "module"在package.json中声明）尝试导入一个CommonJS模块的默认导出时，Node.js会将CJS模块的module.exports对象作为ESM模块的命名导出default属性进行处理，而不是直接将其作为默认导出。这意味着，如果你在CJS模块中有一个默认导出的类，例如：

// Dependency's testFile.ts
export default class TestClass {
    constructor({ arg1 }: { arg1: string }) {
        console.log(arg1);
    }
}

// 编译后的testFile.js大致如下：
"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
class TestClass {
    constructor({ arg1 }) {
        console.log(arg1);
    }
}
exports.default = TestClass; // CJS风格的默认导出

登录后复制

并在ESM项目中尝试以常规方式导入并实例化：

// My project's index.ts (ESM)
import TestClass from "testpackage"; // 期望直接导入TestClass

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

登录后复制

由于ESM导入CJS默认导出时，TestClass实际上是CJS模块对象的一个属性，而非其本身，因此直接调用new TestClass(...)会导致TypeError: TestClass is not a constructor。

错误示例分析

考虑以下项目配置：

ESM项目 (myproject) 配置:

// 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: TestClass is not a constructor

登录后复制

// myproject/tsconfig.json
{
    "include": ["src"],
    "compilerOptions": {
        "outDir": "dist",
        "lib": ["es2023"],
        "target": "es2022",
        "moduleResolution": "node" // 或 "bundler"
    }
}

登录后复制

CJS依赖 (testpackage) 配置:

// 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": {
        "typescript": "^5.0.4"
    }
}

登录后复制

// testpackage/src/testFile.ts
export default class TestClass { // 默认导出类
    constructor({ arg1 }: { arg1: string }) {
        console.log(arg1);
    }
}

登录后复制

// testpackage/tsconfig.json
{
    "include": ["src"],
    "compilerOptions": {
        "declaration": true,
        "lib": ["es2023"],
        "target": "es6",
        "module": "CommonJS", // 编译为CJS模块
        "outDir": "dist"
    }
}

登录后复制

当运行myproject时，会遇到上述的TypeError。如果将myproject的tsconfig.json中的moduleResolution设置为nodenext，TypeScript编译器甚至会在编译时就捕获到这个错误，提示This expression is not constructable. Type 'typeof import("<project_dir>/node_modules/testpackage/dist/testFile")' has no construct signatures.，这进一步印证了TestClass并非直接可构造的。

AI建筑知识问答

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

查看详情

解决方案

针对ESM导入CJS默认导出类时遇到的TypeError，有以下几种解决方案：

1. 通过.default属性访问类

这是最直接且推荐的解决方案，因为它遵循了ESM导入CJS默认导出的行为规范。ESM在导入CJS模块时，会将CJS的module.exports（或exports.default）包装在一个名为default的属性中。因此，我们需要显式地访问这个default属性来获取真正的类构造函数。

// My project's index.ts (ESM)
import Test from "testpackage"; // 导入整个CJS模块对象
const TestClass = Test.default; // 从导入对象中提取默认导出

new TestClass({ arg1: "Hello, World!" }); // 现在可以正确实例化

登录后复制

这种方法清晰地表达了从CJS模块中获取默认导出的意图，并且兼容性良好。

2. 统一模块格式

为了避免模块格式混用带来的复杂性，一个根本的解决方案是确保项目中所有代码都使用同一种模块格式，要么全部ESM，要么全部CJS。

将ESM项目转换为CJS: 如果你的项目对ESM没有强烈的依赖，可以移除package.json中的"type": "module"声明。这样，Node.js会默认将.js文件视为CommonJS模块。同时，可能需要调整tsconfig.json中的module选项为CommonJS。

// myproject/package.json (移除 "type": "module")
{
  "name": "myproject",
  "version": "1.0.0",
  "main": "dist/index.js",
  "scripts": {
    "build": "tsc",
    "start": "node dist/index.js"
  },
  "dependencies": {
    "testpackage": "^1.0.0",
    "typescript": "^5.0.4"
  }
}

登录后复制

// myproject/tsconfig.json (设置 module 为 CommonJS)
{
    "include": ["src"],
    "compilerOptions": {
        "outDir": "dist",
        "lib": ["es2023"],
        "target": "es2022",
        "module": "CommonJS", // 关键改变
        "moduleResolution": "node"
    }
}

登录后复制

在这种情况下，import TestClass from "testpackage";将能正常工作，因为整个项目都以CommonJS方式处理模块。

将CJS依赖转换为ESM: 如果可能，将依赖包也转换为ESM格式是最佳实践。这通常需要修改依赖包的package.json（添加"type": "module"或配置exports字段以支持ESM）和tsconfig.json（设置"module": "ESNext"或类似）。但这通常超出你的控制范围，因为你无法直接修改第三方依赖。

3. 使用Node.js的createRequire函数

Node.js提供了一个createRequire函数，允许在ESM模块内部同步加载CJS模块。这在需要混合使用两种模块系统，且无法通过.default属性解决的复杂场景下非常有用。

// My project's index.ts (ESM)
import { createRequire } from 'module'; // 导入createRequire
const require = createRequire(import.meta.url); // 创建一个require函数，其作用域与当前ESM文件相同

// 使用创建的require函数加载CJS模块
const TestClass = require('testpackage'); 

// 注意：如果CJS模块是exports.default = TestClass; 
// 那么require('testpackage')将直接返回TestClass。
// 如果CJS模块是module.exports = { default: TestClass };
// 那么可能仍需要 TestClass.default。
// 在本例中，CJS的输出是 exports.default = TestClass;
// 因此，直接 require('testpackage') 会返回 { default: TestClass } 对象。
// 所以，我们需要像第一个解决方案一样访问 .default 属性。

const ActualTestClass = TestClass.default || TestClass; // 兼容处理，确保获取到真正的类

new ActualTestClass({ arg1: "Hello, World!" }); // 实例化

登录后复制

注意事项:

createRequire返回的require函数与传统的全局require函数行为一致，它会加载CommonJS模块并返回其module.exports对象。
对于像本例中exports.default = TestClass;的CJS模块，require('testpackage')会返回一个对象{ default: TestClass }。因此，即使使用了createRequire，通常仍需通过.default属性来访问实际的类构造函数。
这种方法主要用于当CJS模块的导出结构比较复杂，或者你希望完全模拟CJS的导入行为时。

总结

解决ESM与CJS默认导出互操作性问题，关键在于理解ESM如何处理CJS的默认导出。最直接且推荐的方法是显式地通过.default属性访问CJS模块的默认导出。如果项目条件允许，统一模块格式（全部ESM或全部CJS）可以从根本上避免这类问题。而createRequire则提供了一种在ESM环境中加载CJS模块的强大工具，适用于特定场景。根据项目的具体需求和可控性，选择最合适的解决方案，可以确保不同模块系统间的平滑集成和代码的正常运行。

以上就是解决ESM与CJS模块默认导出互操作性问题的详细内容，更多请关注php中文网其它相关文章！