VSCode怎么配置无服务器(Serverless)本地调试环境

VSCode 本地调试 Serverless 必须同时满足插件（Debugger for Chrome + Serverless IDE）、CLI 参数（sls offline --debug/--inspect）和 launch.json（type: "node", request: "attach", port: 9229）三者对齐；最常见失败原因是 serverless.yml 中 functions.*.handler 路径错误或未启用调试参数。

开门见山，先说核心结论：想让 VSCode 顺畅地调试 Serverless 本地函数，光靠编辑器本身是行不通的。关键在于让插件、命令行参数和调试配置文件这三者形成“铁三角”，缺了任何一角，调试会话都连不上。而实践中，最容易翻车的往往不是 VSCode 的设置，而是项目配置文件 serverless.yml 里那个不起眼的 handler 路径写错了，或者启动命令 sls offline 时忘了加上关键的 --debug 或 --inspect 参数。

装哪几个插件才真正有用

插件别贪多，装对两个核心的就行，其他无关的甚至建议禁用，以免干扰：

• Debugger for Chrome（或 Debugger for Edge）：别被名字误导，它可不是只用来调浏览器的。它的核心作用是让 VSCode 通过 Node.js 的 --inspect 协议，“附着”到由 sls offline 启动的函数进程上。
• Serverless IDE：这个插件是个“预防针”。它能实时校验 serverless.yml 里 functions.hello.handler 这样的路径，是否真的指向了项目里存在的文件。这就避免了那种令人头疼的 Cannot find module './handler' 错误，非要等到部署（sls deploy）时才暴露出来。
• 禁用 Serverless Framework Extension：这里提个醒，这个老牌插件对 Serverless Framework v3 的兼容性不佳，已经过时了，留着它有时反而会干扰 sls 命令行工具的路径查找。

launch.json 必须配成 attach，不能选 launch

这里有个关键概念需要理解：sls offline 启动的是一个持续运行的服务进程，它不是在执行单次脚本。因此，VSCode 调试器必须采用“附着”（attach）模式，耐心等待 HTTP 请求触发函数后，再介入执行上下文。

• 配置要点：type 设为 "node"，request 必须是 "attach"，port 通常用 9229（这是 sls offline 默认的调试端口）。
• 路径映射：localRoot 填 "${workspaceFolder}"（你的项目根目录），remoteRoot 则要填 "/var/task"（模拟 AWS Lambda 容器内的路径）。两者保持一致，断点映射才能准确无误。
• 版本注意：如果你用的是 serverless-offline@10 或更高版本，默认可能禁用了调试接口，必须显式添加参数，否则 VSCode 会连接失败。

sls offline 启动命令必须带 --debug 或 --inspect

这是另一个常见的“坑点”。如果不加调试参数，sls offline 就只是一个普通的 HTTP 服务器，不会暴露 V8 引擎的调试接口，VSCode 自然也就无从连接。

• 对于 Node.js 函数，推荐这样启动：sls offline --debug --noAuth --port 3000。
• 如果使用了较新的 serverless-offline（v10+），则必须使用 --inspect 参数：sls offline --inspect --noAuth --port 3000。
• 需要警惕的是，即使一切配置正确，断点也不会在服务启动时就激活。你必须先发送一个 HTTP 请求（例如用 curl http://localhost:3000/dev/hello）来触发函数执行，这时 VSCode 才会捕获到调试会话，断点才会生效。

serverless.yml 里 handler 路径错一个字符就白配

毫不夸张地说，本地调试失败，十有八九问题出在这里，而不是 launch.json 或插件。VSCode 不会自动帮你修正拼写错误，而 Serverless IDE 插件通常只是高亮提示，并不会阻止你保存错误的配置。

• 路径严格匹配：仔细检查 functions.hello.handler 的值是否与文件系统中的实际路径完全一致。比如，配置写成 src/handlers/hello.handler，但实际文件却放在 src/functions/hello.js，那么运行时必然会抛出 Cannot find module 错误。
• 格式规范：确保 handler 字段不包含文件扩展名（例如 hello.js 是错误的，应为 hello.handler）。同时，导出的函数名必须与字段的最后一段保持一致（即 hello.handler 对应 module.exports.handler = ...）。
• 语言差异：Python 开发者请注意，格式是 文件名.函数名（如 index.handler 表示 index.py 文件里的 handler 函数），而不是 index.py::handler 这种形式。

最后，还有一个极易被忽略的深层原因：整个调试流程都建立在 sls offline 能够正确加载你的项目结构之上。如果你调整了目录、采用了 monorepo 子包、或者使用了像 serverless-webpack 这样的自定义打包插件，那么 serverless.yml 中配置的 handler 路径，与 sls offline 运行时实际查找的入口文件就可能已经脱节了。这时候，最可靠的方法是查看 sls offline 启动日志中打印的 “Loading function from …” 路径，然后根据这个实际路径，回头去修正 serverless.yml 中的配置。这才是解决问题的根本所在。