Node.js作为服务端JavaScript运行时，模块系统是其核心特性之一，无论是CommonJS的require机制还是ES Module的import机制，都可能因为配置、路径、依赖等问题抛出导入错误，且很多错误提示存在误导性，需要系统排查。
常见误导性导入错误场景
错误提示指向不存在的模块
有时候终端报错会显示找不到某个模块，但实际代码中并没有导入该模块，这种情况通常是间接依赖或者模块解析逻辑异常导致的。
CommonJS和ES Module混用错误
当项目中同时存在两种模块规范，且配置不当时，会出现导入成功但运行报错，或者报错提示模块导出为空的情况，错误提示往往不会直接说明模块类型不匹配的问题。
路径别名解析失败
如果配置了路径别名但对应的解析插件没有生效，错误提示可能会显示找不到原始路径的模块，而不是提示别名解析失败，容易误导排查方向。
排查步骤
第一步：核对错误堆栈信息
不要只看最后一行错误提示，逐行查看错误堆栈，找到第一个指向自己项目代码的调用位置，确定实际触发导入的代码行。
第二步：检查模块导入路径
确认导入路径是否写对，相对路径的层级是否正确，是否遗漏了文件后缀，Node.js默认会尝试解析.js、.json、.node后缀，若文件后缀不对也会报错。
比如下面的导入代码，若当前目录下没有utils.js文件，就会抛出模块找不到的错误：
// 错误示例：导入路径错误
const utils = require('./util'); // 实际文件是utils.js，不是util.js第三步：确认模块类型配置
检查项目根目录的package.json中是否有"type": "module"配置，该配置会决定项目默认使用ES Module还是CommonJS。
- 若配置了
"type": "module"，则默认使用ES Module，此时使用require导入会报错 - 若没有该配置，默认使用CommonJS，使用import导入需要额外配置支持
如果需要在CommonJS模块中使用import，或者ES Module中使用require，需要添加对应的编译配置，否则会出现导入错误。
第四步：检查依赖安装情况
如果是导入第三方模块报错，先检查node_modules目录下是否存在该模块，若没有则需要重新安装依赖，同时确认package.json中是否有该依赖的配置。
若依赖存在但还是报错，可能是依赖版本问题，尝试安装指定版本的依赖解决兼容性问题。
解决方案示例
CommonJS和ES Module混用解决
如果项目是CommonJS类型，要使用ES Module的第三方包，可以通过动态import的方式导入：
// CommonJS模块中导入ES Module包
async function loadModule() {
const module = await import('es-module-package');
console.log(module.default);
}
loadModule();路径别名解析配置
如果使用路径别名，需要对应的解析工具支持，比如在Node.js中可以使用module-alias包配置别名：
// 在入口文件最顶部配置
require('module-alias/register');
// package.json中配置别名
// "module-alias": {
// "@": "./src"
// }
const config = require('@/config'); // 解析为./src/config预防建议
- 统一项目模块规范，避免混用CommonJS和ES Module，若必须混用提前做好兼容配置
- 导入路径尽量写全后缀，减少Node.js解析路径的不确定性
- 第三方依赖版本锁定，避免依赖更新带来的兼容性问题
- 开发时开启Node.js的模块解析日志，方便排查问题，启动时添加
--trace-warnings参数可以查看更详细的警告信息
注意：排查导入错误时不要急于修改代码，先通过错误堆栈和项目配置确定根因，避免无效修改。