断点不生效等调试问题源于通信链路异常：需确保npm初始化、正确配置launch.json（如type为node、request为launch）、Node版本≥14.18.0、关闭Auto Attach、端口未被占用，并针对TS项目启用sourceMap及正确设置runtimeExecutable与env。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
当你在Cursor中调试Node.js项目时遇到报错，比如断点不生效、调试器无法启动、控制台输出乱码或提示“Cannot connect to runtime process”，说明调试配置或环境存在关键缺失。这些问题通常不是代码逻辑错误，而是调试会话与Node.js运行时之间的通信链路出了问题。
确认项目已正确初始化npm并安装依赖
打开终端 → 进入项目根目录 → 执行 npm init -y（若无package.json）→ 运行 npm install 安装所有devDependencies（尤其是typescript、@types/node等调试必需类型包）。
这一步跳过会导致调试器读取不到源映射（source map），断点全部失效，且VS Code/Cursor底层调试协议无法识别入口文件。
配置launch.json调试启动项
在项目根目录下创建 .vscode/launch.json 文件（Cursor复用VS Code调试配置），内容如下：
方法一：调试JavaScript主入口文件
{<br> "version": "0.2.0",<br> "configurations": [<br> {<br> "type": "node",<br> "request": "launch",<br> "name": "Launch via npm start",<br> "runtimeExecutable": "npm",<br> "runtimeArgs": ["run-script", "start"],<br> "console": "integratedTerminal",<br> "skipFiles": ["<node_internals>/**"]<br> }<br> ]<br>}
方法二：直接调试TS文件（需先确保已安装ts-node）
在终端执行 npm install -D ts-node → 修改配置中"runtimeExecutable"为 ts-node → "program"字段指定src/index.ts路径 → 【必须添加"env": {"NODE_OPTIONS": "--enable-source-maps"}】，否则TypeScript断点不会映射到原始代码行。
详细的 Three.js 3D 图形参考，涵盖场景设置、相机、几何体、材质、光照、动画、控制器、加载器、数学工具和调试。
检查Node.js版本与调试端口兼容性
第一步：在终端运行 node --version，确认版本 ≥ 14.18.0（低于此版本不支持--inspect自动附加调试器）。
第二步：打开Cursor设置 → 搜索“debug” → 关闭“Debug > Node: Auto Attach”设为“disabled”，避免多进程调试冲突。
第三步：若使用nodemon热重载，必须在package.json的scripts中将启动命令改为："start": "nodemon --inspect-brk=9229 --exec ts-node src/index.ts" → 启动后等待终端输出Debugger listening on ws://127.0.0.1:9229/...再点击Cursor的绿色▶️按钮附加调试器。
注意：端口号9229不能被其他程序占用，可用lsof -i :9229（macOS/Linux）或netstat -aon | findstr :9229（Windows）查杀残留进程。
修复常见报错信息
报错“Timeout waiting for debug adapter” → 打开launch.json → 在对应配置中增加"timeout": 60000字段，延长等待时间。
报错“Cannot find module 'xxx'” → 检查tsconfig.json中"outDir"和"rootDir"是否匹配，【若使用ESM模块，必须设置"type": "module"且launch.json中添加"runtimeArgs": ["--loader", "ts-node/esm"]】。
报错“Source map not loaded” → 在tsconfig.json中确认已启用"sourceMap": true和"inlineSources": true，并确保编译后的.js文件同目录下存在对应的.js.map文件。
