Medusa调试需用npx medusa develop --inspect-brk启动并VSCode attach，确保tsconfig开启sourceMap、编译输出dist、插件断点打在dist路径，数据库日志通过medusa-config.js配置开启。
Medusa 是基于 Node.js 的开源电商后端，调试它和普通 Express 项目有关键差异：它依赖 CLI 启动、模块热加载机制特殊、且默认不暴露源码映射。直接照搬 Express 调试配置，断点不触发 和 source map not found 是最常见结果。
Medusa 项目启动方式决定调试入口
Medusa 官方推荐用 medusa develop 启动开发服务，该命令会自动处理 TypeScript 编译、插件加载、数据库同步等流程。VSCode 无法直接调试 medusa CLI 二进制本身，必须切入到它实际运行的 JS 入口。
-
medusa develop底层执行的是node --loader ts-node/esm ./node_modules/medusa-cli/dist/index.js develop（TS 项目）或node ./node_modules/medusa-cli/dist/index.js develop（JS 项目），真实服务逻辑最终落在dist/medusa.js或类似路径 - 不要在
launch.json中把program设为"./node_modules/.bin/medusa"—— 这是 shell 脚本，Node 无法直接执行 - 正确做法是：先运行
npx medusa develop --inspect-brk（加--inspect-brk让进程暂停等待调试器连接），再用 VSCode 的attach模式接入 - 若需断点打在你自己的插件或自定义服务里，确保这些代码已编译进
dist/，且tsconfig.json中"sourceMap": true已启用
调试 Medusa 自定义服务或插件时 source map 失效
你在 src/services/my-cart-service.ts 打了断点，但调试器停在 dist/services/my-cart-service.js 的压缩行上，或者提示 Could not read source map —— 这不是 VSCode 问题，是 Medusa 构建链未正确生成或映射 sourcemap。
- 检查
tsconfig.json是否包含："sourceMap": true、"outDir": "./dist"、"rootDir": "./src" - 运行
npx tsc --build后，确认dist/services/my-cart-service.js.map文件存在，且其sources字段指向../../src/services/my-cart-service.ts（路径必须可被 VSCode 从工作区根目录解析） - Medusa CLI 启动时若用了
--no-cache或--watch，可能跳过部分 sourcemap 写入；临时改用npx tsc --build && npx medusa develop确保构建完整 - 在
launch.json的attach配置中，加上"sourceMaps": true和"outFiles": ["${workspaceFolder}/dist/**/*.js"]
多模块联调：同时调试 Medusa + PostgreSQL + 自定义插件
你写了新支付插件，需要观察它和 Medusa 核心服务、PostgreSQL 查询之间的交互，但只 attach 到 Medusa 进程后看不到数据库日志或插件初始化细节。
- PostgreSQL 日志不能通过 VSCode 直接捕获，但可在
medusa-config.js中开启查询日志：database: { type: "postgres", ... logging: ["query", "error"] } - 自定义插件的
load钩子（如afterInit）常在 Medusa 启动早期执行，断点要设在dist/plugins/xxx/index.js对应位置，而非src/—— 因为插件加载走的是 CommonJS require 路径，不经过 TS 编译链 - 避免用
console.log查插件加载顺序；改用debug包：const debug = require("debug")("medusa:plugin:my-payment")，然后终端运行DEBUG=medusa:plugin:* npx medusa develop - 若插件含异步初始化（如连接第三方 API），需在
attach前加--inspect-brk，否则初始化完成才连上，断点就错过了
Medusa 的模块化设计让调试链变长，真正卡住的往往不是 VSCode 配置，而是没意识到 CLI 启动过程分了「编译」、「加载插件」、「连接 DB」、「启动 HTTP 服务」四层，每层都可能提前抛错或跳过你的代码。盯住终端第一行输出，比盲目加断点更有效。
