VSCode无需配置Node环境，只需确保终端中node≥18、pnpm可用且package.json含"type":"module"，再装Volar和Markdown All in One插件，运行pnpm run docs:dev即可启动VitePress。
VSCode 本身不配置 Node 环境，它只复用系统 Shell 的环境；真正要调通 VitePress，关键是让 VSCode 终端里的 node、pnpm（或 npm）命令能正确执行且版本达标——绝大多数“启动失败”“command not found”都卡在这一步，不是 VSCode 设置问题。
确认终端中 node 和 pnpm/npm 版本是否就绪
VSCode 内置终端（Ctrl+`）默认继承系统 Shell，但常因未加载 ~/.zshrc 或 PATH 缺失导致版本错乱：
- 在 VSCode 终端里直接运行
node -v，必须 ≥18（推荐 20+），若报command not found: node，说明 Node 没装或没进 PATH - 运行
pnpm -v（或npm -v），确保有输出；若提示command not found: pnpm，需先全局安装：npm install -g pnpm - Windows 用户注意：Git 必须装且勾选 “Add Git to the system PATH”，否则
pnpm vitepress init会报spawn git ENOENT - macOS/Linux 用户可补一句
source ~/.zshrc强制重载环境变量，再验证版本
package.json 必须声明 "type": "module"
VitePress 的配置文件（如 .vitepress/config.js）是 ESM 模块，VSCode 若按 CommonJS 解析，就会出现 require is not defined、类型跳转失效、自动补全断连等问题：
- 打开项目根目录的
package.json，确认存在这一行："type": "module" - 不要用
.cjs后缀替代——VitePress 官方不保证require()在构建全流程兼容 - 如果用了
config.ts，还需确保已装@types/node，且 VSCode 右下角 TypeScript 版本与项目node_modules/typescript一致（点击可切换） - 删掉
node_modules和pnpm-lock.yaml后重跑pnpm install，避免旧缓存干扰 ESM 解析
插件只装两个关键项：Volar + Markdown All in One
VitePress 的 .md 文件不是纯 Markdown，它含 frontmatter、::: tip 容器、<script setup></script> 等 Vue SFC 语法，VSCode 默认不识别：
- 必须装
Volar（不是Vetur）：它是 Vue 3 + Vite 生态唯一支持.md中 Vue 语法和组件内联提示的语言服务器 - 必须装
Markdown All in One：提供 TOC 生成、标题导航、快捷键（如Ctrl+Shift+P→ “Markdown: Create Table of Contents”） - 禁用所有名字带
VitePress或VuePress的第三方预览插件：它们会劫持渲染逻辑，导致 VSCode 自带预览和浏览器 dev server 表现不一致 - 关掉 VSCode 设置里的
markdown.preview.doubleClickToSwitchToEdit：避免双击预览区意外切回编辑器，打断写作流
启动命令别用错，热更新依赖正确监听路径
vitepress dev 是开发服务，vitepress build 和 vitepress preview 都不启动 HMR，改完文件页面不会自动刷新：
- 启动命令必须是
pnpm run docs:dev（或npm run docs:dev），不是vitepress build - 终端必须在项目根目录执行命令；若在
docs/子目录下运行，监听路径会错，保存后看不到[vite] hot updated:日志 - 别同时开多个终端跑
docs:dev：默认端口5173被占时新进程静默失败，页面白屏但终端无报错；可加参数指定端口：pnpm run docs:dev -- --port 3000 - 终端窗口关掉，服务就停了——
docs:dev是前台进程，不是后台服务
最易被忽略的是：VSCode 终端环境与系统终端不一致这件事，它不像 Webpack 那样有显式报错，而是静默降级成旧 Node 或找不到 pnpm，导致后续所有步骤都错位。动手前先在终端里敲两行 node -v 和 pnpm -v，比调十次配置更有效。
