require('./utils')报Cannot find module主因是VSCode调试时cwd与预期不符，Node按process.cwd()解析路径而非program位置；需在launch.json中显式配置"cwd": "${workspaceFolder}/src"。

为什么 require('./utils') 在 VSCode 调试时总报 Cannot find module

根本不是路径写错了，而是 VSCode 启动调试进程时的当前工作目录（cwd）和你预期的不一致。Node.js 的 require() 是相对 process.cwd() 解析的，不是相对于 program 文件位置。

• 默认情况下，VSCode 调试器的 cwd 是项目根目录（${workspaceFolder}），但如果没显式声明，某些插件或旧版 launch.json 会 fallback 到用户主目录或空路径
• 比如你 program 指向 src/server.js，但 server.js 里写了 require('./utils')，实际会去 ${workspaceFolder}/utils 找，而不是 ${workspaceFolder}/src/utils
• 解决办法：在 launch.json 的 configuration 里加 "cwd": "${workspaceFolder}/src"，让 require() 基于 src 目录解析
• ESM 项目更敏感——import 路径必须是相对或绝对路径，不能省略扩展名（./utils.js），且 cwd 错了会导致 package.json#exports 映射失效

package.json 里 "type": "module" 开了，但断点还是跳不到源码

VSCode 调试器默认按 CommonJS 模式加载文件，即使你用了 ESM，它仍可能忽略 source map 或错误解析 import 路径。

Wjs Localizing Video

用于端到端视频本地化流程的轻量编排器，路由至四个专注子技能——/wjs-transcribing-audio、/wjs-translating-subtitles...

下载

• 必须同时满足三个条件：① package.json 有 "type": "module"；② launch.json 中 "type": "pwa-node"（不是旧版 "node"）；③ sourceMap 正确生成并和 .js 文件同目录
• 如果用 TypeScript 编译 ESM，tsconfig.json 得设 "module": "nodenext" 或 "module": "es2022"，且 "outDir" 和 "rootDir" 对齐，否则 .js.map 里的 sources 字段指向错误路径
• 别信 code-runner 插件——它无视 "type": "module"，强行用 node 命令跑，结果就是 Cannot use import statement outside a module

本地 node -r dotenv/config 生效，但 VSCode 调试里环境变量不加载

VSCode 调试器不会自动继承你在 shell 里通过 dotenv 注入的环境变量，它只读 launch.json 的 env 字段或系统级环境变量。

• 不要依赖 node -r dotenv/config 启动方式——调试器不走这个入口，-r 参数不会被传递
• 正确做法：在 launch.json 的 configuration 里加 "env": {"NODE_ENV": "development"}，再手动加载 .env 文件（例如在 server.js 开头加 require('dotenv').config()）
• 如果要用 dotenv/config，得改用 runtimeExecutable 指向 node，并把 runtimeArgs 设为 ["-r", "dotenv/config", "src/server.js"]，但这样会失去 source map 支持
• 注意：Windows 用户若用 PowerShell 启动 VSCode（code .），.env 文件里的换行符要是 CRLF，否则 dotenv 解析失败，process.env 为空

nodemon --inspect-brk 能热重载，但 VSCode 断点经常失效

不是 nodemon 问题，是 VSCode 的 attach 模式没等进程真正监听调试端口就提前连接，导致断点注册失败。

• 不要在 launch.json 里直接设 "runtimeExecutable": "nodemon"——这是最常见误配，VSCode 会尝试启动 nodemon 进程而非附加到它
• 推荐方案：终端先运行 nodemon --inspect-brk=9229 src/server.js，然后在 launch.json 新建一个 "request": "attach" 配置，指定 "port": 9229，再手动点击「开始调试」
• 加 "restart": true 和 "timeout": 5000 可提升 attach 稳定性，避免因端口未就绪而失败
• 如果用 npm run dev 封装了 nodemon，确保 script 是 "dev": "nodemon --inspect-brk=9229 src/server.js"，而不是 "dev": "nodemon src/server.js"——缺 --inspect-brk 就无法调试

模块化配置真正的复杂点不在语法，而在调试器对模块加载时机、路径解析上下文、环境隔离这三者的耦合处理。哪怕 require 和 import 在运行时表现一致，VSCode 调试器也会因启动方式不同而触发完全不同的解析链。