VSCode本身不提供Node运行时，必须先安装Node.js并正确配置PATH；装完插件不等于环境就绪，90%的“npm run dev不工作”问题源于此。
VSCode 本身不提供 Node 运行时，必须先装好 Node.js 才能运行 Vite；装完插件 ≠ 装好环境，90% 的“npm run dev 不工作”问题都卡在这一步。
Node.js 没装对，Vite 根本启动不了
VSCode 是编辑器，不是运行环境。你在扩展市场搜 “Node.js” 安装的插件（比如 Node.js Extension Pack），只提供语法高亮和代码片段，node 和 npm 命令依然不存在。
- 去 nodejs.org 下载 **LTS 版本**（当前是 v20.15.1），别用 .msi 或 .pkg 包以外的安装方式
- Windows 用户安装时勾选 “Add to PATH”，macOS/Linux 用户确认安装路径已加入 shell 配置（如
~/.zshrc） - 装完后完全退出 VSCode（包括 Dock 右键「退出」或任务管理器杀进程），再重新打开，按
Ctrl+`打开内置终端，立刻执行：node -v和npm -v - 如果报
command not found: node，说明 PATH 没生效——不是 VSCode 问题，是系统环境变量没刷新
npm run dev 启动失败，先看 package.json 和终端输出
Vite 不靠 VSCode 插件启动，它靠 npm run dev 触发。失败通常不是配置错，而是命令写错了或依赖没装全。
- 检查
package.json里的"dev"脚本是不是"vite"（Vite 5+ 默认命令），不是"vite build"或"vite dev" - 终端执行
npm run dev后，等几秒看有没有输出Local:和Network:地址；如果卡在building...或报command not found: vite，说明node_modules/.bin/vite没生成，重装依赖：npm install - 端口被占时 Vite 不会自动换端口，直接报错；可临时指定：
vite --port 3000，或在vite.config.ts中加server.port: 3000
改了代码不热更新，先排除浏览器和 JS 错误
HMR（热模块替换）由 Vite 自动开启，不需要额外配。不生效往往是因为前端阻断或缓存干扰。
- 打开浏览器 DevTools → Network → 勾选
Disable cache（尤其 Chrome） - 看 Console 是否有未捕获错误——一个
ReferenceError就会让 HMR 完全失效 - 确认访问的是
http://localhost:5173，不是file://协议或 Live Server 启的地址，后者断点和 HMR 都不工作 - VSCode 内置终端里跑的
npm run dev进程不能关，关了服务就停，浏览器会报ERR_CONNECTION_REFUSED
VSCode 里一键启动 vite，不用每次敲命令
不需要装所谓“Vite 插件”。VSCode 内置任务系统就能封装 npm run dev 成前台可中断任务。
- 按
Ctrl+Shift+P→ 输入 “Tasks: Configure Task” → 选 “Create tasks.json file from template” → 选 “Others” - 替换内容为：
{
"version": "2.0.0",
"tasks": [
{
"label": "vite:dev",
"type": "shell",
"command": "npm run dev",
"group": "build",
"isBackground": true,
"problemMatcher": [
"$vite"
],
"presentation": {
"echo": true,
"reveal": "always",
"focus": false,
"panel": "shared",
"showReuseMessage": true,
"clear": true
}
}
]
}
保存后，按 Ctrl+Shift+P → “Tasks: Run Build Task” → 选 vite:dev，就能一键启动，终端窗口自动保持前台。
真正容易被忽略的点是：所有调试、热更新、甚至命令能否执行，都建立在 node 和 npm 被 VSCode 终端正确识别的基础上。其他配置都是锦上添花，这一步没走稳，后面全是空转。
