webstorm 对 astro 的支持需满足两个前提：node.js 已安装（v16.12.0+）且官方 astro 插件已启用；否则无法识别 astro dev 脚本，语法高亮、自动导入等功能均失效。
WebStorm 对 Astro 的支持开箱即用，但必须满足两个硬性前提：Node.js 已安装且 Astro 插件已启用。缺一不可，否则连 astro dev 脚本都识别不了，更别说语法高亮或自动导入。
确认 Node.js 和 Astro 插件已就位
WebStorm 不自带 Node.js，也不默认启用 Astro 支持。你得手动检查两件事：
- 终端里运行
node -v，确保输出 v16.12.0 或更高版本；低于这个版本，create astro@latest会失败或生成不兼容的项目 - 进
Settings | Plugins，搜索Astro，勾选并重启 WebStorm —— 注意不是 “Astro Language Support” 这类第三方插件，而是 JetBrains 官方维护的那个，图标是紫色原子符号 - 如果插件列表里搜不到，说明你的 WebStorm 版本太老（早于 2023.3），需升级
用 create astro@latest 初始化项目时别跳过交互步骤
在 WebStorm 内置终端（Alt+F12）中执行命令，不是复制粘贴完就完事。关键点在于向导里的选项会影响后续体验：
- 路径必须写成
./my-astro-site这种相对路径格式，写成my-astro-site或绝对路径，WebStorm 后续可能无法正确识别 Astro 项目结构 - 务必选中 “Yes, use TypeScript” —— 即使你暂时不用 TS，也选它。因为 WebStorm 的 Astro 智能提示（比如
import补全、组件属性推导）严重依赖 TS 类型定义，纯 JS 模式下很多功能会降级或失效 - starter template 建议先选
blank，避免模板里混杂太多配置干扰初期调试
打开已有 Astro 项目时信任项目并装依赖
直接 File | Open 打开一个外部创建的 Astro 项目，WebStorm 会弹出安全提示。这里不能点 “Preview in Safe Mode”：
- “Preview in Safe Mode” 下，
package.json里的dev脚本灰色不可点，src/pages/文件不识别为页面入口，Emmet 缩写完全失效 - 必须点 “Trust Project”，之后立刻在弹窗里点
Run 'npm install'（或对应包管理器）—— 不能等手动去终端敲，否则 WebStorm 不会自动加载node_modules中的类型定义，TS 补全依然不工作 - 装完依赖后，留意右下角是否出现
Astro: Ready提示，没出现说明插件没真正激活，可尝试File | Invalidate Caches and Restart...
运行和调试 astro dev 时注意脚本绑定
WebStorm 默认不会把 package.json 里的 "dev": "astro dev" 当作可运行配置，需要手动触发一次：
- 打开
package.json，在"dev"脚本右侧边距里找绿色三角图标，点击它，WebStorm 就会创建一个名为npm run dev的运行配置 - 首次运行后，以后可以直接按
Ctrl+Shift+F10启动，或者从顶部菜单Run | Run...里选它 - 想断点调试？在
.astro或.ts文件里打debugger，然后用Run | Debug 'npm run dev'启动 —— 注意不是普通 Run，必须是 Debug 模式，否则断点不生效
最容易被忽略的是：Astro 的 SSR 渲染逻辑实际跑在 Node.js 环境里，但 WebStorm 的 Astro 插件对 astro:config 或自定义 integrations 的类型校验很弱。如果你改了 astro.config.mjs 引入新插件，记得手动检查 node_modules 是否真装上了对应包，光靠插件提示容易误判。
