VSCode 必须手动将 .astro 文件关联至 Astro 语言模式，否则语法高亮、补全、跳转均失效；需在 .vscode/settings.json 中配置 "files.associations": {"*.astro": "astro"}，并安装官方 Astro 扩展（非 astro-vscode 旧版），同时确保项目含 astro.config.mjs、已安装 @astrojs/ts-plugin 且 tsconfig.json 启用 "types": ["astro"]。
VSCode 默认不识别 .astro 文件，装了插件也不高亮、没补全、跳转失败——这不是你配错了，是 VSCode 根本没把文件和 Astro 语言模式绑上，类型系统也没加载 Astro 的声明。
如何让 VSCode 正确识别 .astro 文件
核心就一条：VSCode 必须知道 .astro 是 Astro 语言，否则后续所有功能（语法高亮、补全、跳转）都失效。
- 手动临时方案：打开任意
.astro文件 → 点右下角语言标识（常显示为 “Plain Text” 或 “HTML”）→ 输入Astro并选中它 - 一劳永逸方案：在项目根目录的
.vscode/settings.json中加这一行："files.associations": {"*.astro": "astro"} - 如果用的是老版
astro-vscode（v1.x），必须卸载它，改装官方新扩展Astro（发布者是 Astro 官方，带徽章），旧插件已弃用，不支持 Astro v4+ 语法 - 插件启动依赖
astro.config.mjs或astro.config.ts：如果工作区根目录没有这个配置文件，Astro 扩展可能压根不激活语言服务器
astro check 报错但 VSCode 不标红？类型检查没开
VSCode 的 Astro 插件默认只做基础语法解析，astro check 的类型校验（比如 props 类型不匹配、TS 接口错误）它根本不会跑，所以编辑器里一片绿，终端一执行就报错。
- 确保项目已安装
@astrojs/ts-plugin（pnpm add -D @astrojs/ts-plugin），这是 TS 语言服务识别 Astro 类型的关键 - 在
.vscode/settings.json中启用插件调试日志，有助于定位类型加载失败："astro.trace.server": "verbose"
- 更稳的做法：用
eslint-plugin-astro配合 ESLint，它能实时检查组件结构、导入路径、MDX 语法等，比单纯依赖 TS 更贴近开发流 - 注意：
astro check会读tsconfig.json；若项目纯 JS，得配jsconfig.json，否则直接跳过类型检查
IntelliSense 跳转空白、组件没提示、import 不补全
根本原因是 TypeScript 语言服务没加载 astro 类型声明，或者路径没纳入扫描范围。
- 确认
tsconfig.json（或jsconfig.json）里有："include": ["src/**/*"],
且没把src/**/*.{astro,mdx}显式 exclude - 显式引入 Astro 类型声明：
"compilerOptions": { "types": ["astro"] } - 如果用 pnpm，VSCode 可能因 store 路径问题找不到
node_modules/astro，加这行缓解："typescript.preferences.includePackageJsonAutoImports": "auto"
- 组件路径补全弱？推荐装
Path Intellisense插件，它会主动扫描src/下所有文件（含.astro），补全更准
Prettier 格式化 .astro 文件失败
Prettier 原生不支持 .astro，直接保存格式化会静默跳过，或报 Cannot find parser "astro" 错误。
- 必须安装解析器插件：
pnpm add -D @prettier/plugin-astro - 在
prettier.config.js或.prettierrc中配置："overrides": [{"files": "*.astro", "options": {"parser": "astro"}}] - VSCode 设置里确认：
"editor.formatOnSave": true，且默认格式化工具设为 Prettier（不是 ESLint，也不是内置 HTML 格式化） - 可选但实用：用
emeraldwalk.runonsave插件，在保存时触发npm run format，绕过 Prettier 配置复杂度
最常被忽略的点：改了 astro.config.mjs 里的 Vite 配置或输出模式（比如加了 output: 'static'），VSCode 不会自动感知，必须手动重启 dev server；而类型服务一旦加载失败，仅靠重开文件无效，得运行 Developer: Restart TS Server 命令强制刷新。
