第一次在 IntelliJ IDEA 中打开 Node.js 项目时，点击运行后出现 cannot find module 或者断点没有命中，多半是对运行配置和环境准备不够熟悉。IDEA 并不是简单地把 node app.js 封装成一个按钮，它会接管进程的启动参数、环境变量、工作目录和调试端口，一旦某一项设置偏差，运行结果就会和命令行产生差异。下面从环境准备到高级调试逐步梳理，尽量把容易踩到的坑一次说清。

一、运行前准备：解释器选择与项目导入

在 IDEA 中运行 Node.js 前，必须确认当前项目使用的是哪个 Node.js 可执行文件。IDEA 通常会自动检测系统 PATH 中的 node，但在使用 nvm-windows、nvs 或 volta 等多版本管理工具时，自动检测可能指向错误版本。打开 Settings/Preferences 后，找到 Languages and Frameworks 分类下的 Node.js 设置项，手动选择 node 可执行文件。Windows 下的典型路径是 C:\Program Files\nodejs\node.exe，nvm 管理时可能是 C:\Users\你的用户名\AppData\Roaming\nvm\v18.16.0\node.exe。macOS 通过 Homebrew 安装时通常是 /usr/local/bin/node 或 /opt/homebrew/bin/node。

选择解释器后，IDEA 会自动读取对应的 npm 全局路径，这是后续识别脚本和依赖的关键。同一个项目如果换了解释器版本，需要同步检查 npm 路径是否匹配，否则会出现包安装成功但 IDE 仍然提示模块缺失的情况。导入项目时建议直接打开包含 package.json 的目录，而不是只打开单个 JS 文件。IDEA 会根据 package.json 识别项目结构、依赖关系和可用的 npm 脚本，右键 package.json 选择 Show npm Scripts 后，脚本会以树形结构出现在工具窗口中。

下面是一个常见的 package.json 脚本示例，其中 start 用于直接运行，dev 则带上了 inspect 参数方便调试：

{
  "name": "node-debug-demo",
  "version": "1.0.0",
  "scripts": {
    "start": "node app.js",
    "dev": "node --inspect app.js"
  },
  "dependencies": {
    "express": "^4.18.2"
  }
}

如果项目使用了 TypeScript 或者需要额外的 Node 启动参数，比如 --require 预加载模块、--experimental-modules 启用实验特性，可以在 Node.js 设置项的 Node parameters 中统一配置。但要注意，这些参数是整个项目级别的默认值，单个运行配置里还可以再覆盖，避免把所有参数都堆到全局设置中导致其他脚本启动异常。

二、运行配置与断点调试核心操作

运行配置是把解释器、入口文件、工作目录、环境变量、启动参数组合成一个可重复执行的单元。打开 Run 菜单下的 Edit Configurations，点击加号选择 Node.js，会看到几个关键字段。Node interpreter 指定解释器；JavaScript file 指定入口文件，通常填写 app.js 或 src/index.js；Working directory 是进程启动时的当前目录，默认使用项目根目录；Application parameters 用于接收传给脚本本身的参数，例如 --port 8080；Environment variables 用于注入进程环境变量。

配置保存后，IDEA 会生成一个 XML 文件放在项目的 .idea/runConfigurations 目录下。下面是一个简化后的配置示例，展示了主要字段的结构：

<component name="ProjectRunConfigurationManager">
  <configuration default="false" name="debug-app" type="NodeJSConfigurationType" path-to-js-file="app.js" working-dir="$PROJECT_DIR$">
    <method v="2" />
  </configuration>
</component>

启动调试时不要点击普通的运行按钮，而要选择 Debug 模式，也就是工具栏上的小虫子图标。IDEA 会启动一个独立的 Node 进程，并附加到 V8 调试协议上。断点设置在编辑器左侧行号区域，单击即可打红色断点。调试启动后，Variables 面板会展示当前作用域内的变量，包括局部变量、闭包变量和全局对象；Frames 面板显示调用栈，可以逐层查看上层函数的参数和状态。F8 表示 Step Over，F7 表示 Step Into，Shift+F8 表示 Step Out，这些快捷键和大部分 IDE 快捷键一致。

与命令行调试相比，IDEA 的内置调试器能直接展开对象属性、数组元素和 Promise 状态，不必在终端中用 console.log 逐个打印。但它也有一个明显限制：默认情况下，对于 Node.js 内置模块的源码，可能需要手动下载对应版本的 Node.js 源码文件，才能在调试时进入内置模块内部查看。如果发现断点无法命中内部文件，先检查 Settings 中 Node.js 源码是否已关联，而不是急着修改代码。

三、环境变量、参数传递与端口占用

环境变量在 Node.js 中通过 process.env 读取，配置不当最容易导致 undefined。在 IDEA 的 Environment variables 输入框中，格式是每行一个 KEY=VALUE，不要加 export 前缀，也不要写成 JSON 对象。例如：

NODE_ENV=development
DATABASE_URL=postgres://localhost:5432/mydb

工作目录同样重要。Node.js 脚本中 process.cwd() 返回的是进程启动时的当前目录，而 __dirname 是当前模块文件所在目录，两者不一定相同。如果代码里使用相对路径读写文件，比如 fs.readFileSync('./data.json')，但工作目录没有设置为项目根目录，就会报 ENOENT 错误。建议在调试配置中始终将 Working directory 显式设置为 $PROJECT_DIR$，避免依赖 IDE 的默认行为。

端口占用是另一个高频问题。如果调试时提示 Error: listen EADDRINUSE，说明目标端口已经被占用，可能是上一个 Node 进程没有正常退出。可以先在终端运行 netstat -ano | findstr :3000（Windows）或 lsof -i :3000（macOS/Linux）找到占用进程并结束它。在代码层面，可以让端口从环境变量读取，避免多次运行冲突：

const port = process.env.PORT || 3000;
const server = app.listen(port, function() {
  console.log('Server running at http://127.0.0.1:' + port);
});

这样可以方便地在调试配置中修改 PORT 环境变量，而不必改动代码。同时注意 Windows 下结束 Node 进程时，如果 IDEA 中的停止按钮没有完全杀死子进程，可以在任务管理器中查找 node.exe 并手动结束，下次再启动就不会出现端口冲突。

四、Source Map 与 TypeScript 调试

调试 TypeScript 项目时，断点必须映射回原始的 .ts 文件，而不是编译后的 dist 目录中的 .js 文件。要做到这一点，首先要在 tsconfig.json 中开启 sourceMap 选项，并指定输出目录：

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "sourceMap": true,
    "outDir": "./dist"
  },
  "include": ["src/**/*"]
}

在 IDEA 中创建 Node.js 调试配置时，入口文件应该选择编译后的 JS 文件，例如 dist/server.js，而不是原始的 src/server.ts。IDEA 会读取 JS 文件末尾的 sourceMappingURL 注释，自动找到对应的 .ts 文件。然后在 .ts 文件中打断点，断点会同步命中。如果断点变成灰色圆圈或提示 invalid breakpoint，先检查 outDir 是否与实际编译输出一致，再看 sourceMap 路径中是否包含了绝对路径或错误的前缀。

远程调试也是 Source Map 经常出错的场景。当 Node.js 应用运行在 Docker 容器或远程服务器上时，需要以 inspect 模式启动并开放调试端口。例如在服务器上执行：

node --inspect=0.0.0.0:9229 dist/server.js

然后在 IDEA 中添加一个 Attach to Node.js/Chrome 类型的调试配置，Host 填服务器 IP 或 127.0.0.1（如果做了端口转发），Port 填 9229。连接成功后，IDEA 会读取远程进程的源码映射信息。如果此时断点不命中，很可能是远程服务器上的源码路径和本地不一致，或者没有同步对应的 .ts 文件。解决方式是把源码目录映射到本地对应的项目路径，或者调整 sourceRoot 配置。

除了上述场景，还常见两个问题：一是 Node 版本与 IDEA 不兼容导致的调试协议握手失败，建议将 IDEA 升级到较新版本；二是调试器附加后变量面板中看不到某些闭包变量，这通常是因为 V8 优化了作用域，可以尝试在断点附近添加一个 debugger 语句强制暂停，或把变量先赋值给一个全局变量再观察。

五、常见问题排查清单与注意事项

在多版本 Node.js 切换后，IDEA 可能仍然使用旧的解释器缓存。表现为终端里 node -v 已经显示新版本，但 IDE 的运行配置仍然指向旧路径。解决方法是重新打开 Settings 中的 Node.js 设置，点击解释器路径右侧的浏览按钮重新选择 node 可执行文件，然后点击 Apply。必要时执行 File 菜单下的 Invalidate Caches 并重启 IDE，以清除内部索引。

关于模块解析失败，除了检查解释器路径和 npm 安装目录，还要注意 node_modules 是否存在符号链接。使用 pnpm 或 yarn workspaces 的项目中，依赖可能被提升到根目录，IDEA 的模块解析有时会忽略这些软链接。此时可以在 Project Structure 中手动标记源目录和资源目录，或者把 node_modules 加入项目的 Libraries 中。另外，如果 package.json 中定义了 type: module，而运行配置没有启用 ES modules 支持，启动时会出现 SyntaxError 或 ERR_REQUIRE_ESM。这时可以在 Node parameters 中加上 --experimental-vm-modules 或者直接使用 --input-type=module，并确保入口文件使用 .mjs 或 package.json 的 type 字段正确。

还有一个容易被忽略的问题是 IDEA 的调试器超时设置。当应用启动后需要连接数据库或远程服务，如果这些外部依赖响应很慢，调试器可能会在连接前超时断开。在 Run/Debug Configurations 的 Node.js 配置中，找到 Startup 或 Connection 相关选项，适当增大超时时间，可以避免刚进入调试模式就报错的情况。

总结下来，在 IntelliJ IDEA 中运行和调试 Node.js 并不是单纯地点一下运行按钮，而是要把解释器、工作目录、环境变量、启动参数和源码映射这五个环节都配置到位。每次出现异常先按照这个顺序排查：解释器是否指向正确的 node、工作目录是否准确、环境变量有没有漏掉、入口文件和参数是否正确、Source Map 是否有效。把这套检查流程固化下来，可以显著减少调试配置带来的时间浪费，把精力集中在业务逻辑本身。