vscode 开箱即可运行 vitepress 项目，只需安装 volar 和 markdown all in one 插件、确保 package.json 含 "type": "module"、终端环境匹配 node ≥18 及包管理器，并用 pnpm vitepress dev 启动。
VSCode 本身不需要额外“配置 VitePress 开发环境”，只要装对插件、设好工作区、避免 require() 报错，开箱就能跑文档项目。
安装 Vue 官方插件和 Markdown 预览支持
VSCode 默认不识别 Vue SFC 和 VitePress 的 Markdown 前置声明（如 ---\ntitle: xxx\n---），不装插件会导致语法高亮错乱、跳转失效、智能提示缺失。
- 必须安装
Volar（非 Vetur）：Vue 3 + Vite 生态的官方语言服务器，支持.md中的<script setup></script>和组件内联提示 - 推荐安装
Markdown All in One：增强标题导航、TOC 生成、快捷键（如Ctrl+Shift+P→ “Markdown: Create Table of Contents”） - 可选装
ESLint+Prettier：如果项目启用了vitepress lint或自定义校验规则，需在工作区启用对应配置
确保工作区识别为 ESM 模块
VitePress 的 .vitepress/config.js（或 .ts）默认用 ES 模块语法，但 VSCode 可能按 CommonJS 解析，导致 import 正常而 require() 报错，或自动补全失效。
- 检查项目根目录
package.json是否含"type": "module"；没有就加上 - 若用
.ts配置文件（如config.ts），确保已安装@types/node和typescript，且 VSCode 工作区 TypeScript 版本与项目一致（右下角点击 TS 版本可切换） - 不推荐改后缀为
.cjs：VitePress 官方不保证require()在所有构建阶段兼容
启动开发服务前先确认终端环境
VSCode 内置终端（Ctrl+`）默认复用系统 Shell，但 Node.js 版本、pnpm/npm 切换、PATH 环境变量可能和外部终端不一致，导致 npx vitepress dev 启动失败或报 command not found。
- 在 VSCode 终端中执行
node -v和pnpm -v（或对应包管理器），确认版本 ≥18 且与文档要求一致 - 若用 pnpm，确保已全局安装（
npm install -g pnpm），或在终端中运行source ~/.zshrc（macOS/Linux）或刷新 Windows PATH - 首次运行前，建议手动执行一次
pnpm install（或npm install），避免 VSCode 终端缓存旧依赖状态
调试时别忽略 .vitepress/dist 的产出路径
VitePress 构建产物默认输出到 docs/.vitepress/dist，但 VSCode 的 Live Server 插件或内置预览不会自动监听该路径——它只认 index.html 所在目录。直接双击打开 dist/index.html 会因相对路径错误白屏。
- 不要用 Live Server 打开
dist目录：它无法代理 VitePress 的路由逻辑（如/guide/→/guide/index.html） - 正确做法是始终用命令行启动：
pnpm vitepress dev，然后访问http://localhost:5173 - 如需离线预览构建结果，应部署到真实 HTTP 服务（如
npx serve -s docs/.vitepress/dist），而非文件协议
最容易被忽略的是 package.json 中 "type": "module" 缺失，以及 VSCode 终端未加载 shell 配置导致 pnpm/npm 不可用——这两个问题占本地启动失败的七成以上。
