vscode无需特殊配置node环境，只需确保终端能调用vitepress命令、项目含"type":"module"、安装volar和markdown all in one插件，并用pnpm docs:dev启动；报command not found或require is not defined均源于环境未对齐或模块类型缺失。
VSCode 本身不“配置” Node 环境，它只复用你系统已有的 Node 和包管理器；真正要做的，是让 VSCode 终端能正确调用 vitepress 命令、识别 ESM 模块、并避免插件干扰 Markdown 渲染。
终端里执行 vitepress dev 报 command not found
这不是 VSCode 的问题，而是终端没找到可执行的 vitepress。常见原因和应对方式：
- 没全局安装
vitepress：VitePress 是本地开发依赖，应通过pnpm add -D vitepress（或npm install --save-dev vitepress）装在项目里，然后用pnpm vitepress dev启动，而非vitepress dev -
pnpm或npm命令本身不可用：检查node -v≥ 18 且pnpm -v有输出；macOS/Linux 用户可能需要在 VSCode 终端中先运行source ~/.zshrc，Windows 用户需确认 PATH 已包含 pnpm 安装路径 - 用了错误的启动脚本：package.json 中应有类似
"docs:dev": "vitepress dev docs"的 script，直接运行pnpm docs:dev更可靠，避免路径错位
require is not defined 或 import 报错
这是典型的模块系统不匹配——VitePress 要求 ESM，而 VSCode 默认可能按 CommonJS 解析 .vitepress/config.js。
- 必须在项目根目录
package.json中添加"type": "module"，否则import会被降级处理，require()在浏览器环境根本不存在 - 如果用
config.ts，确保已安装@types/node，且 VSCode 右下角显示的 TypeScript 版本与项目node_modules/typescript一致（点击可切换） - 别把
config.js改成config.cjs：VitePress 官方不保证require()在所有构建阶段可用，强行改后缀反而引发更多兼容性问题
Markdown 编辑卡顿、预览不生效、<script setup></script> 无提示
VSCode 默认不理解 VitePress 的 Markdown 扩展语法（如 frontmatter、自定义容器、内联 Vue 脚本），必须靠插件补能力，但装错会更糟。
- 必装
Volar（不是Vetur）：它是 Vue 3 + Vite 生态官方语言服务器，唯一能解析.md文件中<script setup></script>并提供组件提示的插件 - 必装
Markdown All in One：支持 TOC 生成、标题导航、快捷键（如Ctrl+Shift+P→ “Markdown: Create Table of Contents”） - 禁用所有名字含
VitePress或VuePress的第三方 Markdown 预览插件：它们会劫持渲染流程，导致 VSCode 内置预览和浏览器 dev server 表现不一致 - 关闭设置
markdown.preview.doubleClickToSwitchToEdit：双击预览区意外切回编辑模式，打断写作流
改了 index.md 页面却不刷新
热更新（HMR）没触发，通常不是 VitePress 失效，而是进程没跑对或监听路径不对。
- 确认用的是
pnpm docs:dev（或等效命令），不是vitepress build—— 后者只生成静态文件，不启动开发服务器 - 别关掉运行
docs:dev的终端窗口：VitePress dev server 是前台进程，窗口关闭即服务终止，浏览器报ERR_CONNECTION_REFUSED - 检查终端是否有类似
[vite] hot updated: /docs/index.md的日志：没有就说明监听路径错误，确保你在docs目录下执行命令，或命令中明确指定路径（如pnpm vitepress dev docs） - 端口被占时默认静默失败：若同时开了多个终端运行
docs:dev，第二个会因 5173 端口占用而无声退出，可加参数指定端口：pnpm docs:dev -- --port 3000
真正容易被忽略的是：VSCode 终端是否接管了前台进程、package.json 是否真的写了 "type": "module"、以及有没有无意中启用冲突的 Markdown 插件——这三处出错，90% 的“配置失败”就发生了。
