vscode无需特殊配置vitepress，只需装volar和markdown all in one插件、在package.json加"type": "module"、确保终端node≥18且pnpm可用，再运行pnpm run docs:dev即可启动。
VSCode 不需要“配置” VitePress，只要插件、模块类型、终端环境三者对齐，vitepress dev 就能直接跑起来——绝大多数报错都卡在这三处，不是 VSCode 本身的问题。
为什么 vitepress dev 启动失败或命令未找到
根本原因通常是终端环境与系统不一致，而非 VSCode 设置问题：
- VSCode 内置终端（
Ctrl+`）默认复用 shell，但可能没加载~/.zshrc或PATH，导致pnpm或node版本不对；执行node -v和pnpm -v确认 ≥18 且有输出 -
command not found: vitepress：说明pnpm add -D vitepress没成功，或安装后没重新运行pnpm install（VSCode 终端有时缓存旧 node_modules） - Windows 下
spawn git ENOENT：pnpm vitepress init依赖 git 初始化，必须装 Git for Windows 并勾选 “Add Git to the system PATH” - 国内网络下
npm add -D vitepress卡住：先运行npm config set registry https://registry.npmmirror.com，再重试
VSCode 打开 .md 文件语法错乱、跳转失效、<script setup></script> 无提示
这是缺少语言服务器支持的典型表现，VitePress 的 Markdown 不是纯文本，它嵌入 Vue SFC 语法和 frontmatter，VSCode 默认不识别：
- 必须装 Volar（不是 Vetur），它是 Vue 3 + Vite 生态唯一支持
.md中<script setup></script>和组件内联提示的语言服务器 - 装 Markdown All in One：补全 TOC 生成、标题导航、
Ctrl+Shift+P → “Markdown: Create Table of Contents”等高频操作 - 别装“Markdown Preview Enhanced”之类老插件：它们会劫持预览逻辑，和 VitePress 的热更新冲突，导致改完保存页面不刷新
package.json 缺 "type": "module" 导致 require() 报错或自动补全失效
VitePress 的 .vitepress/config.js（或 .ts）是 ESM 模块，VSCode 若按 CommonJS 解析，就会在 import 正常的情况下仍报 require is not defined，或无法跳转到 defineConfig 类型定义：
- 在
package.json根目录加一行："type": "module"，不要用.cjs后缀替代——VitePress 官方不保证require()在所有构建阶段兼容 - 如果用
config.ts，确保已装@types/node，且 VSCode 右下角 TypeScript 版本与项目一致（点击可切换工作区 TS 版本） - 删掉
node_modules和pnpm-lock.yaml后重装依赖，避免旧缓存干扰 ESM 解析
主题配置生效但页面白屏或路由 404
这不是主题写错了，而是开发服务没走 VitePress 的 dev server，或者产物路径被误用：
- 永远用
pnpm run docs:dev（或对应 script），别直接vitepress dev docs——后者不读package.json中的 scripts 配置，可能绕过自定义 alias 或 base - 别用 Live Server 插件打开
.vitepress/dist/index.html：它不代理 VitePress 的路由规则（如/guide/→/guide/index.html），必白屏 - 若部署到非根路径（如
/docs/），必须在config.js中显式设base: '/docs/'，否则构建后静态资源路径全错 - 改了
config.js但页面没反应？检查终端是否有 HMR 日志；没有就说明监听失效，常见于同时开了两个docs:dev进程占用了 5173 端口，加--port 3000换端口再试
最易被忽略的是终端环境与插件协同：Volar 必须启用、"type": "module" 必须存在、pnpm run docs:dev 必须在正确版本的终端里执行——这三者缺一不可，少一个，VSCode 就只是个高级记事本。
