必须先装好 Node.js、cordova、ionic CLI，再用 VSCode 打开项目根目录并配好终端和调试配置；否则 ionic serve 报错、cordova build 卡死或连不上设备。
ionic 开发环境在 VSCode 中不是“装个插件就跑起来”，而是依赖一整套命令行工具链。直接上结论：必须先装好 Node.js、cordova、ionic CLI，再用 VSCode 打开项目并配好终端和调试配置；否则 ionic serve 会报错、ionic cordova build 会卡死或连不上设备。
Node.js 和 npm 源必须提前调好
很多 ionic start 失败，根本不是 Ionic 问题，是 npm 卡在下载依赖上。Windows 下尤其明显：
-
npm install -g ionic cordova前，先执行npm config set registry https://registry.npm.taobao.org（或https://registry.npmmirror.com） - 确认
node -v≥ 16.14.0（Ionic 7+ 要求），npm -v≥ 8.19.0 - 如果用 cnpm，所有命令要换成
cnpm install -g ionic cordova，且后续一律用cnpm，别混用 - PowerShell 或 CMD 启动时，避免以普通用户身份运行——某些
cordova platform add在 Win10/11 上需要管理员权限才写入platforms/
ionic start 创建项目后，VSCode 要直接打开根目录
不是打开 www 或 src 子文件夹，而是打开整个项目文件夹（含 package.json、ionic.config.json）。否则：
- VSCode 终端里执行
ionic serve会提示 “Not an Ionic project” - 自动保存刷新（Live Reload）不生效，因为
ionic serve的 watch 机制依赖项目根下的配置 - Ctrl+Shift+B 运行任务失败，因 tasks.json 中的
--path指向错误（老教程里写c:\...\www已过时，Ionic 4+ 用的是src/+ 构建输出）
VSCode 终端默认用 PowerShell，但 Cordova 需要 cmd 或 Git Bash
Windows 上 ionic cordova build android 报 EACCES、spawn gradle ENOENT 或卡在 “Checking Java JDK and Android SDK versions…”——大概率是终端 shell 不兼容。
- 在 VSCode 里按
Ctrl+Shift+P→ 输入 “Terminal: Select Default Profile”，选Command Prompt或Git Bash - 确认已设好环境变量：
JAVA_HOME（指向 JDK 17）、ANDROID_SDK_ROOT（指向 Android SDK 根目录）、PATH包含%ANDROID_SDK_ROOT%platform-tools和%ANDROID_SDK_ROOT% ools - 不要信“自动检测通过”——进终端手动跑
java -version、adb --version、gradle -v，三者都得有输出
ionic serve 端口被占或热更新失效？改 launch.json 不够
VSCode 默认没配调试器，ionic serve 只是起一个本地 dev server。常见现象：浏览器打不开、F5 刷新白屏、修改代码不自动更新。
- 先关掉其他占用 8100 端口的程序（比如另一个
ionic serve、旧版 Ripple、甚至 Skype） - 在项目根下运行
ionic serve --port 8101换端口试试 - 如需断点调试 TypeScript，得手动加
.vscode/launch.json，内容不能只抄旧模板：{ "version": "0.2.0", "configurations": [{ "type": "pwa-chrome", "request": "launch", "name": "Launch in Chrome", "url": "http://localhost:8100", "webRoot": "${workspaceFolder}/src", "sourceMapPathOverrides": { "webpack:/*": "${webRoot}/*" } }] } - 注意：Ionic 7 默认用
vite构建，ionic serve实际调的是vite dev，所以 source map 路径和旧 Angular CLI 项目不同，sourceMapPathOverrides必须匹配当前构建器输出
真正卡住的地方，往往不在 VSCode 设置，而在 ANDROID_SDK_ROOT 指向了 Android Studio 自动管理的路径（带空格或版本号），或 ionic CLI 版本和项目 ionic-angular / @ionic/angular 版本不匹配。这些细节不手动验证，光靠“一键搭建”脚本永远跑不起来。
