云函数本地调试必须通过 cloudbase cli 的 functions:dev 命令启动并配合 vscode attach 模式，而非微信开发者工具或 launch 模式；需全局安装 @cloudbase/cli，正确配置 launch.json（address/port 匹配 cli 启动参数），使用 event.json 模拟真实请求，并手动重启进程以应用代码修改。
云函数本地调试必须用 cloudbase CLI 启动，VSCode 无法直接 attach
微信开发者工具自带的云函数本地调试（右键“在本地模拟器中运行”）不走 VSCode 的 debugger，所以你在 VSCode 里打的断点完全不会生效。真正能配合 VSCode 调试的，只有 cloudbase CLI 提供的 cloudbase functions:dev 模式——它会启动一个带 --inspect 参数的 Node.js 进程。
常见错误现象：launch.json 配了 attach 类型但一直显示 “waiting for connection”，或者控制台报 Connection refused。根本原因是没先跑起 cloudbase functions:dev，VSCode 在干等一个根本不存在的调试端口。
- 必须先全局安装：
npm install -g @cloudbase/cli（注意不是tcb-cli，老版本已废弃） - 项目根目录下执行：
cloudbase functions:dev --function-name yourFunctionName（支持多函数，用逗号分隔） - 该命令默认监听
9229端口，且自动启用--inspect=0.0.0.0:9229，无需手动加参数 - 确保本地
cloudbase配置正确：项目根目录有cloudbaserc.json，且envId和region填对了
launch.json 必须用 attach 模式，且 port 和 address 要匹配 CLI 启动参数
cloudbase functions:dev 默认绑定 0.0.0.0:9229，但 VSCode 的 Node.js debugger 默认只连 localhost:9229。如果本地网络策略或防火墙限制了 0.0.0.0，就得显式指定 address。
典型配置（放在项目根目录 .vscode/launch.json 中）：
支持AI生成符合公众号规范的图文，推送至草稿箱；兼容其他技能生成的图文/图片。通过向导扫码授权，支持多账号；无需暴露Secret密钥或配置IP白名单。
{
"version": "0.2.0",
"configurations": [
{
"type": "node",
"request": "attach",
"name": "CloudBase Function Debug",
"port": 9229,
"address": "localhost",
"localRoot": "${workspaceFolder}",
"remoteRoot": "/",
"skipFiles": ["<node_internals>/**"]
}
]
}
</node_internals>
-
"request": "attach"是唯一可行方式；launch模式会尝试自己拉起进程，但云函数依赖cloudbase的上下文注入（如cloud对象、环境变量），自己启动会报ReferenceError: cloud is not defined - 如果 CLI 启动时加了
--inspect=127.0.0.1:9230，那这里port和address就得同步改成9230和"127.0.0.1" -
remoteRoot: "/"很关键：因为cloudbaseCLI 启动时把函数代码挂载在容器根路径，不是按工作区路径映射的，设错会导致断点灰色（source map 不匹配）
云函数里不能直接用 console.log 查 event 或 context，要靠 debugger 看变量面板
本地调试时，cloudbase functions:dev 会模拟微信调用，但传入的 event 是 CLI 自动生成的 JSON 文件内容（默认读 event.json），不是开发者工具里点击触发的实时数据。很多人习惯在函数开头写 console.log(event)，结果看到的是空对象或默认模板——其实是因为没配 --event-file 参数。
- 想调试真实请求结构，先建一个
event.json放到函数目录下，内容按云函数实际接收格式写（比如含openid、data字段） - 启动时加参数：
cloudbase functions:dev --function-name fn1 --event-file ./fn1/event.json - 更可靠的方式是直接在
index.js第一行打个断点，运行后在 VSCode 变量面板里展开event和context，比日志更准——尤其context里的envId、functionName都是 CLI 注入的，console.log可能被截断或异步延迟 - 注意：云函数里
require('cloud') !== require('@cloudbase/node-sdk')，前者是微信小程序 SDK，在本地调试时必须用后者，否则cloud.callFunction会失败
调试时修改代码不会热更新，每次改完都得重启 cloudbase functions:dev
cloudbase functions:dev 当前版本（v1.15+）不支持文件监听和自动重启，这点和 nodemon 完全不同。你改完 index.js，保存后继续点 VSCode 的“重新连接”，只会提示 “Cannot connect to runtime process”——因为旧进程还占着 9229 端口，新进程根本没起来。
- 最省事的做法：在终端里按
Ctrl+C终止当前cloudbase functions:dev，再回车重跑一遍命令 - 可以配个 npm script 简化：
"dev:fn": "cloudbase functions:dev --function-name myFn --event-file ./myFn/event.json"，然后用npm run dev:fn - 别指望
restart按钮：VSCode 的 debug restart 功能对attach模式无效，它不会帮你杀进程 - 如果你同时调试多个函数，得开多个终端分别跑
cloudbase functions:dev，每个函数独占一个调试端口（可用--inspect-port指定）
真正的难点不在配置，而在于接受「云函数本地调试本质是 Node.js 进程调试」这个事实——它不经过微信开发者工具，也不走小程序框架生命周期，所有依赖都要手动补全，比如数据库连接、登录态 mock、跨域头设置，这些都不会自动继承自线上环境。
