解决JavaScript模块导入错误：ESM与CommonJS的兼容性实践-js教程-PHP中文网

解决JavaScript模块导入错误：ESM与CommonJS的兼容性实践

聖光之護

发布： 2025-11-14 16:16:12

原创

566人浏览过

解决JavaScript模块导入错误：ESM与CommonJS的兼容性实践

本教程旨在解决javascript开发中，尤其是在尝试使用esm的`import`语法导入模块时遇到的`unexpected token '*'`错误。该问题常见于浏览器环境或特定构建流程中，当模块实际为commonjs格式时。文章将详细解释这一兼容性挑战，并提供一种有效的解决方案：在node.js环境中，通过`require`语法结合解构赋值来正确导入commonjs模块，确保项目顺利运行。

在现代JavaScript开发中，模块化是组织和重用代码的核心机制。目前主要存在两种主流的模块系统：ES Modules (ESM) 和 CommonJS (CJS)。ESM 使用 import 和 export 关键字，是 ECMAScript 标准的一部分，通常在浏览器和最新的Node.js环境中得到原生支持（通过 type="module" 或 .mjs 文件）。CommonJS 则使用 require 和 module.exports，主要在Node.js环境中广泛应用。

理解模块导入中的Unexpected token '*'错误

当开发者尝试在项目中使用ESM的 import * as ModuleName from 'module-name' 语法导入一个模块时，如果遇到 Unexpected token '*' 错误，这通常意味着你正在尝试以ESM的方式导入一个实际上是CommonJS格式的模块，而当前运行环境（无论是浏览器还是Node.js）未能正确地解析或转译这种混合模式。

以 obs-websocket-js 库为例，它可能是一个主要以CommonJS格式发布的库。当你在一个期望ESM的环境中（例如，一个配置为 type="module" 的脚本或某些构建工具链）使用 import * as OBSWebSocket from 'obs-websocket-js' 时，JavaScript引擎会因为无法理解CommonJS模块的导出结构而抛出语法错误，因为它遇到了不符合ESM规范的*通配符。

解决方案：拥抱CommonJS的require机制

解决这类兼容性问题的最直接方法是根据模块的实际导出格式和运行环境来选择正确的导入语法。对于在Node.js环境中运行，且目标模块（如 obs-websocket-js）是CommonJS格式的情况，使用 require 机制是最佳实践。

立即学习“Java免费学习笔记（深入）”；

挖错网

一款支持文本、图片、视频纠错和AIGC检测的内容审核校对平台。

查看详情

当一个CommonJS模块使用 module.exports = SomeClass; 这样的形式导出时，它实际上是导出了一个默认值。在ESM中，这会被视为 default 导出。在CommonJS环境中，我们可以通过解构赋值来获取这个默认导出，并将其重命名以便使用。

以下是具体的解决方案代码示例：

// 导入 obs-websocket-js 模块
// 使用 require 导入 CommonJS 模块，并通过解构赋值获取其默认导出
// { default: OBSWebSocket } 表示从 require 导入的对象中，
// 取出名为 'default' 的属性，并将其重命名为 OBSWebSocket
var { default: OBSWebSocket } = require('obs-websocket-js');

// 创建 OBSWebSocket 实例
const obs = new OBSWebSocket();

// 连接到 OBS WebSocket 服务器
// 注意：obs.connect 是一个异步操作，返回 Promise
obs.connect('ws://192.168.1.143:4455', "YOUR_OBS_PASSWORD")
    .then(() => {
        console.log('成功连接到 OBS WebSocket！');
        // 连接成功后，可以监听事件
        obs.on('CurrentProgramSceneChanged', scene => {
            console.log(`当前场景已切换到: ${scene.sceneName}`);
        });
    })
    .catch(err => {
        console.error('连接 OBS WebSocket 失败:', err);
        // 根据错误类型进行处理，例如重试连接
    });

// 监听 WebSocket 连接本身的错误事件，提高健壮性
obs.on('error', err => {
    console.error('OBS WebSocket 发生错误:', err);
});

// 监听断开连接事件
obs.on('Identified', () => {
    console.log('OBS WebSocket 已识别并连接。');
});

obs.on('ConnectionClosed', () => {
    console.log('OBS WebSocket 连接已关闭。');
});

登录后复制

代码解析：

var { default: OBSWebSocket } = require('obs-websocket-js');
- require('obs-websocket-js')：这是Node.js中导入CommonJS模块的标准方式。它会返回模块导出的整个对象。
- { default: OBSWebSocket }：如果 obs-websocket-js 库将其主要类或功能作为 module.exports = MyClass; 导出，那么在Node.js中通过 require 获得的实际上就是 MyClass 本身。然而，为了与ESM的 default 导出概念兼容，当通过某些工具或特定方式处理时，这个默认导出可能会被包装在一个 { default: MyClass } 的对象中。这里我们显式地从 require 返回的对象中解构出名为 default 的属性，并将其赋值给 OBSWebSocket 变量。这确保了无论底层导出是直接的CommonJS默认导出还是被包装过的，我们都能正确获取到 OBSWebSocket 类。
const obs = new OBSWebSocket();：使用获取到的 OBSWebSocket 类创建实例。
obs.connect(...).then().catch()：connect 方法返回一个 Promise，因此需要使用 .then() 和 .catch() 来处理连接的成功与失败，确保异步操作的正确执行。
obs.on(...)：注册事件监听器，以响应OBS WebSocket服务器发出的事件，例如场景切换。

注意事项与最佳实践

环境匹配： 此解决方案主要适用于Node.js环境。如果你是在纯浏览器环境（没有构建工具）中遇到此问题，并且必须使用 import 语法，那么你需要确保所导入的库提供ESM版本，或者使用像Webpack、Rollup、Parcel这样的模块打包工具来将CommonJS模块转换为浏览器可用的ESM或UMD格式。
异步操作处理： WebSocket连接通常是异步的。务必使用 Promise（.then().catch()）或 async/await 来处理 obs.connect() 等异步方法，以避免竞态条件和未处理的错误。
错误处理： 除了连接错误，还应监听 obs.on('error', ...) 事件，以捕获WebSocket连接过程中可能出现的其他运行时错误，增强应用程序的健壮性。
凭据安全： 在实际部署中，OBS WebSocket的IP地址和密码等敏感信息不应直接硬编码在代码中，而应通过环境变量、配置文件或安全的服务端获取。
模块版本： 随着库的更新，其模块导出方式可能会发生变化。如果遇到问题，请查阅 obs-websocket-js 官方文档，确认其推荐的导入方式。

总结

Unexpected token '*' 错误是JavaScript模块系统兼容性问题的一个典型表现。理解ESM和CommonJS之间的差异，并根据项目运行环境和目标模块的实际导出格式选择正确的导入方式至关重要。对于在Node.js环境中导入CommonJS模块，采用 require 结合解构赋值（尤其是处理 default 导出）是一种高效且可靠的解决方案。通过这种方式，我们可以确保应用程序能够顺利地集成和使用各种JavaScript库。

以上就是解决JavaScript模块导入错误：ESM与CommonJS的兼容性实践的详细内容，更多请关注php中文网其它相关文章！