VSCode调试Hono项目必须用tsx启动，因其依赖JSX/TSX语法、顶层await及ESM特性，直接node运行会报Cannot use import statement outside a module或Unexpected token '<'。
VSCode 调试 Hono 项目必须用 tsx 启动，不能直接跑 node —— 否则必报 Cannot use import statement outside a module 或 Unexpected token '。
为什么 launch.json 里 runtimeExecutable 必须指向 tsx 而不是 node
Hono 默认启用 JSX/TSX 写法（比如 app.get("/", () => <div></div>)）、顶层 await、JSON 模块导入等纯 ESM 特性。Node.js 原生不支持这些语法，node index.ts 会直接崩溃。tsx 是专为现代 TS/ESM 设计的运行时，能无缝处理所有这些特性。
实操建议：
- 本地安装：
npm install -D tsx（或pnpm add -D tsx） -
runtimeExecutable设为"./node_modules/.bin/tsx"（Windows 下路径分隔符用\或保持/通常也兼容） - 不要加
"--loader", "ts-node/esm"—— 这是旧方案，和 Hono 的原生 ESM 加载链冲突 - 若用 pnpm，
runtimeExecutable可写绝对路径（如"./node_modules/.bin/tsx"），避免依赖npx（调试中不可靠）
为什么 sourceMaps: true 会让断点变灰、无法命中
Hono 是直接运行 TS 源码，不经过 tsc 编译输出 .js 文件。VSCode 调试器若开启 sourceMaps，会尝试从 .js.map 映射回源码 —— 但根本不存在这些文件，于是找不到原始 .ts 行，断点失效。
实操建议：
- 显式设
"sourceMaps": false（默认值，但写出来更稳） - 删掉或注释掉
outFiles字段（它只在编译输出场景下有用） -
type必须是"pwa-node"，不是"node"—— 新版 VSCode 对 ESM 的完整支持仅在pwa-node下可用
修改代码后服务不热重载？这不是 bug，是调试器默认行为
F5 启动调试时，VSCode 不会自动监听文件变化。你改了 index.ts，进程不会重启，新断点也不会生效 —— 这是设计如此，不是配置错误。
两种可靠解法：
- 终端手动运行：
npx tsx watch index.ts，再在launch.json中用attach模式连接（"request": "attach", "port": 9229） - 或在
launch.json的runtimeArgs中加["--watch"]（仅限tsx v4+），但注意：首次断点可能延迟 1–2 秒 - 顺手关掉 VSCode 的
debug.javascript.autoAttachFilter（设为"disabled"），否则它会抢连其他 Node 进程，干扰你的调试
HTTP 请求 404 或连接拒绝？先查 app.listen() 是否真正生效
app.listen(3000) 在调试中容易静默失败：端口被占用、绑定 127.0.0.1 却用 localhost 访问（DNS 解析差异）、或 process.env.PORT 被覆盖导致监听失败。
实操建议：
- 启动后立刻检查控制台输出，确认有类似
Listening on http://localhost:3000的日志 - 用
curl -v http://127.0.0.1:3000测试，排除 DNS 层问题 - 在
listen()后加一句console.log("✅ Server ready")，确保执行流走到这里 - 边缘部署前，本地务必验证路由是否响应 —— Hono 的
app.get()不会自动 fallback，路径错一点就是 404
最易被忽略的一点：Hono 项目调试成功 ≠ 边缘部署就通。Cloudflare Workers 要求导出 default handler，且不能有顶层 console.log 外的副作用；tsx 能跑通的本地代码，可能在 wrangler dev 下报错。本地调试只是第一步，边缘环境的约束得单独验证。
