VSCode无需特殊配置VitePress，只需确保终端能运行vitepress dev、安装Volar和Markdown All in One插件、package.json含"type": "module"，否则常见问题源于终端环境、插件冲突或ESM配置缺失。
VSCode 本身不需要“配置” VitePress，只要终端能跑 vitepress dev、插件不干扰 Markdown 渲染、项目是 ESM 模块，开箱就能实时预览——绝大多数卡住的问题，都出在终端环境、插件冲突或 package.json 缺 "type": "module" 这三处。
为什么 index.md 改了但页面没刷新？
不是 VitePress 失效，而是热更新（HMR）根本没触发。常见原因：
- 终端里误用了
vitepress build或vitepress preview：这两个命令不启动开发服务器，只生成静态文件，自然不会监听变更 - 同时开了多个终端运行
pnpm docs:dev：默认端口5173被占，新进程静默失败，终端无报错但页面白屏 - VSCode 内置终端没接管前台进程：关掉运行
docs:dev的终端窗口，服务就停了，浏览器报ERR_CONNECTION_REFUSED - 文件保存后没看到终端输出类似
[vite] hot updated: /docs/index.md的日志：说明监听路径不对，检查是否在docs目录外执行命令
VSCode 预览 Markdown 为啥高亮错乱、跳转失效？
因为默认的 Markdown 支持不认识 VitePress 的语法扩展，比如 frontmatter --- 块、::: tip 容器、<script setup></script> 块。必须靠插件补全能力：
- 必装
Volar：不是Vetur，它才是 Vue 3 + Vite 生态的官方语言支持，能解析.md里的 Vue 语法和组件提示 - 必装
Markdown All in One：提供 TOC 生成、标题导航、快捷键（如Ctrl+Shift+P → "Markdown: Create Table of Contents"） - 禁用所有名字带
VitePress或VuePress的第三方 Markdown 预览插件：它们会劫持渲染流程，导致 VSCode 自带预览和浏览器 dev server 表现不一致 - 关闭 VSCode 设置里的
markdown.preview.doubleClickToSwitchToEdit：避免双击预览区意外切回编辑模式，打断写作流
终端报 command not found: vitepress 或 require() not supported 怎么办？
前者是环境没搭好，后者是模块系统不匹配。两个问题常一起出现：
- 先确认
node -v≥ 18、pnpm -v（或npm -v）有输出：VSCode 终端可能复用旧 shell 环境，执行source ~/.zshrc（macOS/Linux）或重启终端 - 检查项目根目录
package.json是否含"type": "module"：没有就加上，否则.vitepress/config.js里的import会被当 CommonJS 解析，引发require is not defined - 如果用了
config.ts，确保已安装@types/node，且 VSCode 右下角显示的 TypeScript 版本与项目node_modules/typescript一致（点击可切换） - 别改配置文件后缀为
.cjs：VitePress 官方不保证require()在所有构建阶段兼容，强行绕过只会埋坑
真正容易被忽略的是：VitePress 构建产物在 .vitepress/dist，但这个目录不能直接用 VSCode 的 Live Server 插件打开——它不代理路由，/guide/ 会 404。调试时务必用 pnpm docs:dev 启服务，而不是双击打开 dist/index.html。
