必须显式启用sourceMap才能调试MinIO SDK调用链，否则VSCode断点为空心红圈；需在launch.json中设"sourceMaps": true，并确保构建生成.map文件，同时用console.assert校验初始化参数防静默失败。
launch.json 配置必须显式启用 sourceMap 才能调试 MinIO SDK 调用链
MinIO 官方 JS SDK（@minio/minio-js）基于 xmlhttprequest 和底层流操作，编译后代码经过 Webpack/Babel 处理，若项目未开启 source map，VSCode 断点会变成空心红圈，尤其在 client.putObject() 或 client.getObject() 回调里完全无法停住。
解决方法是在 launch.json 的配置中加入 "sourceMaps": true，并确认构建时生成了 .map 文件：
- 使用 TypeScript 项目：确保
tsconfig.json中"sourceMap": true已开启 - 使用 Vite 构建的 Node 后端（如 vite-node）：需在
vite.config.ts中设build.sourcemap = 'inline' - 纯 JS + CommonJS 项目：若用
node --inspect模式，可加"protocol": "inspector"并配合 Chrome DevTools 查看原始 SDK 源码
MinIO 客户端初始化失败时，调试器常静默退出——先查 ERR_INVALID_ARG_VALUE
常见错误是 new Minio.Client() 构造函数传入了空字符串或 undefined 的 endPoint / accessKey，Node.js 会抛 ERR_INVALID_ARG_VALUE，但 VSCode 调试器不会弹错误提示，只显示“Debug session terminated”，控制台也无输出。
实操建议：
- 在
Minio.Client实例化前加console.assert(endPoint && accessKey, 'MinIO config missing')，确保断点能捕获到早期失败 - 不要依赖
process.env.MINIO_ENDPOINT直接传参——调试时环境变量可能未加载，改用require('dotenv').config()显式加载，并在launch.json中通过"env"字段覆盖："env": { "NODE_ENV": "development", "MINIO_ENDPOINT": "localhost:9000" } - MinIO 服务未启动时，
client.bucketExists()会卡住约 30 秒才 reject，建议在调试前先执行curl -I http://localhost:9000/minio/health/live快速验证连通性
在 async/await 中对 getObject() 流式响应设断点容易跳过
client.getObject() 返回的是 ReadableStream，直接在 const stream = await client.getObject(...) 这行设断点没用——它只是返回流对象，不触发实际网络请求。真正读取发生在 stream.on('data', ...) 或 stream.pipe(...) 时，而这些回调是异步微任务，VSCode 默认不跟踪。
推荐做法：
- 把流消费逻辑封装成独立
async函数，例如async function readObjectStream(stream) { for await (const chunk of stream) { ... } }，然后在此函数第一行设断点 - 避免在
.on('data')回调里设断点；改用stream.pipe(new Writable({ write(chunk, _, cb) { debugger; cb(); } }))，让debugger语句强制进入调试模式 - 如果用
stream.toString()简单读取小文件，可在该调用后立即设断点，此时 V8 已完成流消费
MinIO 本地开发用 Docker 启动时，network_mode 影响 VSCode 断点可达性
很多人用 docker run -p 9000:9000 启动 MinIO，但在 macOS 或 Windows 上，Docker Desktop 的网络栈和宿主机间有层 NAT，VSCode 调试器发起的 HTTP 请求可能被重定向或超时，表现为 getBucketPolicy() 永远 pending。
关键修复点：
- 启动 MinIO 容器时加
--network host（Linux）或改用host.docker.internal:9000作为endPoint（macOS/Windows） - 在
launch.json的"env"中硬编码"MINIO_ENDPOINT": "host.docker.internal:9000"，避免开发机 hosts 文件未映射导致解析失败 - 不要在
program字段里写绝对路径如/Users/xxx/project/src/server.js——用"${workspaceFolder}/src/server.js"，否则 Docker 内部路径和宿主机不一致会导致 source map 绑定失败
MinIO 联调最易忽略的是：SDK 的 Client 实例本身不是 Promise，所有方法都返回 Promise 或 Stream，但构造函数失败不会 throw，而是静默失效。务必在初始化后立刻调用 client.ping() 或 client.listBuckets() 做存活探测，并在该 await 行设断点——这是唯一能确认网络、认证、权限三者同时就绪的位置。
