断点不生效需改用 node --inspect-brk 启动并配置 launch.json；服务端逻辑须触发请求后调试；source map 和端口配置必须准确，且区分客户端与服务端执行环境。
调试 Astro 组件时断点不生效？检查 astro:dev 启动模式
Astro 默认用 astro dev 启动开发服务器，但 VSCode 调试需要它以调试友好的方式运行——即启用 source map 并暴露调试端口。直接运行命令行里的 astro dev 不会自动开启 Node.js 调试协议（DAP），VSCode 找不到目标进程。
- 必须改用
node --inspect-brk node_modules/astro/dist/cli.js dev启动，才能让 VSCode 附加到进程 - 推荐在
.vscode/launch.json中配一个Attach to Astro类型的配置，而不是Launch Program - 确保
astro.config.mjs里没禁用 source map：build: { sourcemap: true }（开发模式下默认开启，但自定义 build 配置可能覆盖） - 组件内断点只在客户端渲染部分（如
use:client或内联<script></script>）生效；纯服务端组件（如.astro模板逻辑）断点需配合服务端调试配置
VSCode 报错 “Cannot connect to runtime process”？检查端口和 launch.json 配置
常见于启动后立刻尝试 Attach，但 Node.js 还没完成初始化、调试端口尚未就绪；或端口被占用、防火墙拦截。
- 在
launch.json中明确指定port（如9229），并在启动命令中保持一致：node --inspect-brk=9229 ... -
address字段不要写localhost，用127.0.0.1更稳妥，某些系统 DNS 解析会导致连接失败 - 加
"timeout": 10000避免 VSCode 在端口未就绪时快速报错退出 - 确认没有其他 Node 进程占着同一端口：终端执行
lsof -i :9229（macOS/Linux）或netstat -ano | findstr :9229（Windows）
服务端代码（如 API Routes、getStaticPaths）怎么断点？要区分运行时环境
Astro 的服务端逻辑实际跑在 Vite 开发服务器内部的 Node.js 上，但不是独立进程——它被封装在 Vite 的 HMR 服务中，不能像普通 Express 项目那样直接 attach 到一个入口文件。
- API Routes（
src/pages/api/*.ts）和服务端函数（getStaticPaths、getStaticProps）只能通过Attach to Astro方式调试，且断点必须设在请求触发后才加载的模块里 - 首次请求前，相关代码尚未被 Vite 加载，断点会显示为空心圆（unbound），需先发一次请求（比如 curl
curl http://localhost:4321/api/test），再在 VSCode 里按 F5 继续 - 如果用了
output: "serverless"或"hybrid"模式，调试行为不变，但 source map 路径映射可能出错，建议暂时切回"static"模式验证调试链路
为什么 console.log 输出位置混乱？别依赖终端输出看服务端日志
VSCode 调试器接管了 stdout/stderr，但 Astro/Vite 的日志混合了服务端、客户端、HMR 多个通道，终端里看到的 console.log 可能来自任意一层，且顺序不可靠。
- 服务端
console.log实际输出到 VSCode 的Debug Console，不是Terminal标签页 - 组件脚本里的
console.log仍走浏览器控制台，和调试器无关；想统一查看，改用debugger语句 + 断点更可靠 - 避免在
getStaticPaths等构建时函数里写大量console.log，它们只在astro build阶段执行，astro dev下不会触发
调试 Astro 的难点不在配置本身，而在于它把多个执行环境（Vite 服务端、客户端 hydration、SSR 渲染）揉在一个进程里——断点是否生效，取决于你此刻调试的是哪一层、代码是否已被加载、source map 是否准确映射到原始 .astro 文件。稍有不匹配，VSCode 就静默跳过。
