program字段不能写相对路径，必须用${workspaceFolder}拼接为workspace-relative路径（如"${workspaceFolder}/packages/api/src/index.js"）或绝对路径，否则报Cannot find module；需显式设置cwd指向对应package目录，确保依赖和sourceMap正确解析。

launch.json 里 program 字段不能写相对路径

VS Code 调试器在 Mono-Repo 中启动子包时，program 必须是相对于 cwd 的绝对路径或 workspace-relative 路径（用 ${workspaceFolder} 拼接），否则会报 Cannot find module 或直接退出。常见错误是直接填 "src/index.js"，而没指定该文件实际属于哪个 package。

• 正确写法示例："program": "${workspaceFolder}/packages/api/src/index.js"
• 若使用 npm start 启动，改用 runtimeExecutable: "npm" + runtimeArgs: ["run", "start"]，但需确保 cwd 指向对应 package 目录
• cwd 字段必须显式设置，否则默认为 workspace 根目录，导致 require() 找不到 node_modules 下的本地依赖（比如 packages/utils）

本地 package 依赖无法被调试器识别

Monorepo 中常用 pnpm link 或 npm link，但 VS Code 调试器不会自动解析 symbolic link，也不会读取 pnpm-workspace.yaml 的 packages 配置。结果是断点能打上，但跳转进本地依赖（如 packages/db）时停不下来，console.log 也看不到变量值。

Rydberg Agent Node

使用一条命令部署ProbeChain Rydberg测试网代理节点。自动注册为Agent(NodeType=1)，免gas，支持macOS/Linux/Windows。触发词：/r

下载

• 解决方案：在对应 package 的 launch.json 中加 "outFiles": ["${workspaceFolder}/packages/*/lib/**/*.js"]，并确保构建产物（如 lib/）存在且 source map 已生成
• 更可靠的做法是启用 sourceMap: true 并在 tsconfig.json 中设 "inlineSources": true, "inlineSourceMap": true（TypeScript 场景）
• 如果用 ESM，注意 Node.js 默认不支持 .ts 文件的 import，得靠 tsx 或 ts-node --esm，此时 runtimeExecutable 要指向对应二进制，而不是 node

多个服务同时调试时端口和 inspector 冲突

默认所有 Node 进程都尝试绑定 9229，VS Code 启动第二个调试配置时会报 address already in use，或者断点只在一个服务生效。

• 每个 configurations 必须单独配 port，例如："port": 9230、"port": 9231
• 配合 "autoAttachChildProcesses": true，避免子进程（如 fork 出的 worker）脱离调试上下文
• 若用 nodemon 或 ts-node-dev，禁用其内置 watch，改用 VS Code 的 preLaunchTask 触发 rebuild，否则热重载会干扰调试器 attach

env 和 envFile 不能混用，dotenv 不自动生效

env 字段写进 launch.json 是唯一可靠的环境变量注入方式；.env 文件不会被 VS Code 加载，即使你代码里写了 require('dotenv').config()，调试器启动时仍可能因 process.env 缺失而失败（比如数据库连接字符串为空）。

• 不要依赖 envFile 字段——它只对某些调试器类型（如 Python）有效，type: "node" 完全忽略它
• 把所有关键变量（NODE_ENV、DB_URL、PORT）显式写进 env 对象，值可用 ${env:HOME} 引用系统变量
• 敏感变量（如 API key）别硬编码，用 process.env + env 配置项传递，别塞进 launch.json 提交到 Git

调试 Mono-Repo 的难点不在配置多，而在每个 package 的执行上下文是否干净独立——cwd、env、node_modules 路径、source map 位置，四者缺一不可。漏掉任意一个，断点就成摆设。