VSCode 需手动关联 .astro 文件到 Astro 语言模式，并配置 tsconfig.json 含 "astro" 类型、启用 @astrojs/ts-plugin 或 eslint-plugin-astro，重启 TS 服务方可支持语法高亮、类型检查与 IntelliSense。
安装 Astro 扩展后项目仍不识别 .astro 文件
VSCode 默认不识别 Astro 文件类型，即使装了官方扩展，也常因语言模式未正确关联而高亮错乱、无语法提示。核心问题是 VSCode 没把 .astro 后缀和 Astro 语言模式绑定。
- 手动触发：打开任意
.astro文件 → 点击右下角语言标识（如显示“Plain Text”）→ 输入Astro并选择它 - 一劳永逸：在工作区根目录的
.vscode/settings.json中加这一行："files.associations": {"*.astro": "astro"} - 若用的是旧版
astro-vscode（v1.x），必须卸载并安装新扩展Astro（作者是astro官方），老插件已弃用且不支持 v4+ 语法
astro check 报错但 VSCode 不报红
VSCode 的 Astro 扩展默认只做基础语法检查，不运行 astro check 这类类型校验，所以 TS 类型错误、组件 props 类型不匹配等，在编辑器里完全没提示，直到终端运行才暴露。
- 启用类型检查：在
.vscode/settings.json中开启"astro.trace.server": "verbose"
并确保项目已安装@astrojs/ts-plugin - 更可靠的做法：在 VSCode 中配置任务运行
astro check，或使用eslint-plugin-astro配合 ESLint 插件，它能实时标出组件结构、导入路径等问题 - 注意
astro check依赖项目有tsconfig.json；若项目用 JS 开发，需额外配jsconfig.json，否则检查直接跳过
热更新（HMR）失效或刷新整个页面
Astro 默认对组件内 JS/TS 做 HMR，但对 src/layouts/ 或 src/pages/ 下的顶层逻辑变更，常触发整页刷新——这不是配置错误，而是 Astro 的设计限制：这些文件属于构建入口层，改动即重编译路由。
- 局部预览技巧：在
.astro组件中用export const prerender = false强制走客户端渲染，可提升 HMR 响应速度 - 禁用服务端渲染调试：启动时加
--host --port 3000 --dev参数，并确认没有output: 'static'卡住开发服务器 - 若改了
astro:config里的内容（比如vite配置），必须重启 dev server；VSCode 不会自动感知astro.config.mjs变更
IntelliSense 提示缺失或跳转失败
常见于导入自定义组件、工具函数或 TypeScript 类型时，Ctrl+Click 跳转空白、import 行没补全、组件属性无提示——根本原因是 TS 语言服务没加载 Astro 的类型声明，或路径别名未被识别。
- 确保项目根目录有
tsconfig.json，且包含"compilerOptions": {"types": ["astro"]} - 如果用了
src/外路径（如lib/utils.ts），需在tsconfig.json的"baseUrl"和"paths"中显式声明，否则 VSCode 的 TS Server 直接忽略 - 重启 TS 服务：Cmd/Ctrl + Shift + P → 输入 “TypeScript: Restart TS server”，比重启 VSCode 更快生效
Astro 的类型系统深度依赖 TS 配置和扩展版本匹配，一个没对齐，IntelliSense 就退化成纯文本搜索。别指望“装了就灵”，得一个个对齐路径、类型声明、插件版本。
