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、类型跳转失效、自动补全断连等问题：

Vite

为开发、生产构建和库打包配置并优化 Vite。

下载

• 打开项目根目录的 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，比调十次配置更有效。