Wrangler CLI 必须全局安装，VSCode 仅是编辑器，本地调试完全依赖 wrangler CLI；需手动端口转发 8787，正确配置 compatibility_date 和 node_compat，并在源码而非 .wrangler/ 文件中设断点。
Wrangler CLI 必须全局安装，VSCode 本身不提供 Workers 运行时
VSCode 只是编辑器，Cloudflare Workers 的本地调试完全依赖 wrangler CLI。没装好 CLI，所有插件或配置都白搭。
实操建议：
- 用
npm install -g wrangler或brew install cloudflare/tap/wrangler安装（推荐后者，版本更新更稳） - 运行
wrangler --version确认输出类似wrangler 3.65.0，不是command not found - 别用
npx wrangler替代全局安装——本地开发中频繁触发wrangler dev时，npx 每次重解压会明显卡顿 - 如果用 pnpm，需额外加
-g并确保$HOME/.pnpm/bin在$PATH中，否则 VSCode 终端可能找不到命令
VSCode 需要手动启用 wrangler dev 的端口代理，否则 localhost:8787 打不开
wrangler dev 默认启动在 localhost:8787，但 VSCode 内置终端不自动转发该端口，浏览器直连会失败（ERR_CONNECTION_REFUSED）。
实操建议：
- 在 VSCode 中打开项目根目录后，按
Ctrl+Shift+P（macOS 是Cmd+Shift+P），输入 “Ports: Forward a Port”，回车 - 输入
8787，选择 “Forward to Localhost” - 此时 VSCode 底部状态栏会出现
8787 → localhost:8787，点击它可直接在浏览器打开 - 别依赖 “Live Server” 插件——它起的是 HTTP 服务器，和
wrangler dev的 Miniflare 沙箱完全无关
wrangler.toml 里 compatibility_date 和 node_compat = true 容易配错
这两个配置直接影响你能否用 require()、fs.readFile 或最新 Web API（如 TextEncoderStream）。配错会导致本地能跑、部署报错，或反之。
实操建议：
-
compatibility_date = "2024-05-01"—— 建议设为当前日期，避免因日期过旧导致本地支持但生产环境不支持新语法 -
node_compat = true仅在你明确用了 Node.js 兼容层（比如import { readFile } from "node:fs/promises"）时才开；开了会略微拖慢冷启动，且部分 API（如process.env）行为与真实 Workers 不一致 - 若用 ES modules（
import）且无 Node 依赖，保持node_compat = false更贴近生产行为 - 检查错误信息：如果看到
ReferenceError: require is not defined，说明代码用了 CommonJS 但node_compat = false；如果看到TypeError: TextEncoder is not a constructor，大概率是compatibility_date太老
调试断点只能打在源码上，不能打在生成的 .wrangler/ 临时文件里
wrangler dev 启动后会在 .wrangler/ 下生成 bundle 和 sourcemap，但 VSCode 的 Debugger（即使装了 “Cloudflare Workers” 插件）默认不识别这些路径映射，直接在生成文件里打断点无效。
实操建议：
- 确保项目根目录有
.vscode/launch.json，内容含"type": "pwa-node"和"request": "launch"，并设置"runtimeExecutable": "wrangler"和"args": ["dev"] - 关键：在
launch.json中加入"sourceMaps": true和"outFiles": ["${workspaceFolder}/.wrangler/**/*.js"] - 断点必须打在你写的
src/index.ts或index.js上，VSCode 会自动映射到运行时代码；打在.wrangler/.../worker.js里毫无反应 - 如果断点灰了（unbound），先检查
wrangler dev是否已启动，再确认launch.json中的outFiles路径是否匹配实际生成位置（不同 wrangler 版本路径略有差异）
最常被忽略的是 sourcemap 路径匹配和 compatibility_date 的时效性——这两处一错，本地和线上行为就可能分裂，而且错误不报在控制台，只在请求响应里静默失败。
