VSCode调试Hono项目必须用tsx启动，因其依赖JSX/TSX、顶层await等ESM特性；需配置pwa-node类型、禁用sourceMaps、正确设置runtimeExecutable路径，并确保tsx版本与调试器匹配。
VSCode 调试 Hono 项目必须用 tsx 启动，不能直接跑 node
因为 Hono 默认依赖 JSX/TSX 语法（比如 app.get("/", () => <div></div>)），且大量使用顶层 await、模块 JSON 导入等 ES 模块特性。直接用 node index.ts 会报 Cannot use import statement outside a module 或 Unexpected token '<'。
实操建议：
- 确保已全局或本地安装
tsx：npm install -D tsx - 在
.vscode/launch.json中，runtimeExecutable设为./node_modules/.bin/tsx（Windows 下注意路径分隔符） - 不要设
runtimeArgs为["--loader", "ts-node/esm"]—— 这是旧方案，和 Hono 的 ESM + JSX 冲突 - 如果用 pnpm，
runtimeExecutable改成./node_modules/.bin/tsx或直接写绝对路径（npx在调试中不可靠）
launch.json 配置里 sourceMaps 和 outFiles 必须关掉
Hono 是纯 ESM + TS 直接运行，不经过 tsc 编译输出 .js 文件。启用 sourceMaps: true 或配 outFiles 反而会让 VSCode 找不到原始 .ts 文件，断点全灰掉。
实操建议：
-
sourceMaps设为false（默认就是 false，但显式写出来更稳） - 删掉
outFiles字段，或注释掉 - 确认
type是pwa-node（不是node），新版 VSCode 调试器对 ESM 支持只在pwa-node下完整 - 加
"env": { "NODE_OPTIONS": "--enable-source-maps" }没用，tsx自己管 sourcemap，且 Hono 不需要它
修改代码后热重载失效？检查 tsx watch 是否被调试器绕过
VSCode 调试模式默认不触发文件监听。你改了 index.ts，服务不会自动重启，断点也不会更新到新代码行 —— 这不是 bug，是设计如此。
实操建议：
- 开发时别只靠 F5 启动：终端手动跑
npx tsx watch index.ts，再用 VSCode 的 Attach 功能连接（type: "pwa-node",request: "attach",port: 9229） - 或者，在
launch.json里加"runtimeArgs": ["--watch"]（仅限tsxv4+），但注意：watch 模式下首次断点可能延迟 1–2 秒 - 禁用 VSCode 的
autoAttach（设置里搜debug.javascript.autoAttachFilter，设为disabled），否则它会抢连其他node进程，干扰调试
HTTP 请求进不来？确认 app.listen() 的端口没被复用或绑定失败
Hono 的 app.listen(3000) 在调试中容易静默失败：比如端口被占用、监听 127.0.0.1 却用 localhost 访问（DNS 解析差异）、或 process.env.PORT 被其他插件覆盖。
实操建议：
- 启动后立刻看调试控制台输出 —— 成功会打印
Listening on http://localhost:3000；没这句，大概率listen()抛错被捕获吞掉了 - 在
app.listen()后加.catch(console.error)，例如：app.listen(3000).catch(console.error) - 避免用
0.0.0.0:3000（尤其在 WSL 或 Docker 环境），优先用127.0.0.1:3000或留空（app.listen(3000)默认行为更稳） - 检查防火墙或公司代理软件（如 Clash、Surge）是否劫持了本地 3000 端口 —— 这类问题不会报错，但请求根本到不了 Hono
最常被跳过的其实是 tsx 版本和 launch.json 中 type 的匹配问题：v4+ 的 tsx 要求 pwa-node，v3 则可能 fallback 到旧调试器，断点行为不一致。真遇到断点不命中，先 npx tsx --version 和 launch 配置对一眼。
