vitepress 本身不依赖 vscode 特殊配置，但开箱即用需满足三个前提：vitepress 命令可执行、index.md 能被正确解析、vscode 不干扰 markdown 渲染与热更新；常见失败原因集中于 npm/pnpm 镜像配置、init 权限问题及插件冲突。
直接上结论：VitePress 本身不依赖 VSCode 特殊配置，但开箱即用的前提是——vitepress 命令能跑起来、index.md 能被正确解析、VSCode 不干扰 Markdown 渲染和热更新。多数“配置失败”问题，其实卡在 npm/pnpm 镜像、vitepress init 权限、或 VSCode 插件冲突这三处。
npm 或 pnpm 安装 vitepress 失败的常见原因
不是 Node 版本不够新（v20+ 即可），而是 registry 或权限拦住了。国内用户最常遇到的是：
-
npm add -D vitepress卡住或报ETIMEDOUT：必须提前设淘宝镜像，命令是npm config set registry https://registry.npmmirror.com，注意set后面没等号，别写成configset - 用
pnpm却提示command not found：说明没全局安装 pnpm，先运行npm install -g pnpm，再验证pnpm -v - Windows 下
npx vitepress init报错spawn git ENOENT：Git 没装或没加进 PATH，去官网下完整 Git for Windows，安装时勾选 “Add Git to the system PATH”
VSCode 打开 VitePress 项目后预览不刷新
这不是 VitePress 的锅，是 VSCode 终端没接管好进程，或你误用了构建命令。关键点：
- 启动命令必须是
npm run docs:dev（或pnpm docs:dev），不是vitepress build，后者只生成静态文件，不启 dev server - VSCode 内置终端里执行命令后，别关掉那个终端窗口——VitePress dev server 是前台进程，关了就停服务，浏览器白屏或报
ERR_CONNECTION_REFUSED - 如果改了
index.md但页面没变，先看终端有没有 HMR（hot module replacement）日志，没有就说明监听失效；检查是否开了多个终端同时跑docs:dev，端口被占（默认 5173），可加参数npm run docs:dev -- --port 3000
Markdown 编辑体验差：预览不实时、语法高亮错乱
VitePress 用标准 Markdown，但 VSCode 默认的 Markdown 预览不支持 VitePress 特有的 frontmatter（如 --- layout: home ---）和自定义容器（::: tip）。要解决：
- 装插件只留两个必要项：
Markdown All in One（增强编辑）、Markdown Preview Mermaid Support（如果用了流程图）；禁用所有带 “VitePress” “VuePress” 字样的第三方预览插件，它们会抢渲染权导致冲突 - VSCode 设置里关掉
markdown.preview.doubleClickToSwitchToEditor，否则点预览区会意外切回编辑器，打断写作流 -
index.md顶部的 YAML frontmatter 必须顶格写，开头不能有空行或空格，否则vitepress dev启动时会静默跳过该文件，首页变成 404
自定义主题或配置后本地预览正常，但部署到 GitHub Pages 报 404
这是路径问题，不是代码 bug。VitePress 默认输出为根路径（/），但 GitHub Pages 仓库若非用户名.github.io，而是 username.github.io/repo-name，就必须告诉 VitePress 基础路径：
- 在
.vitepress/config.js（或config.mjs）里加base: '/repo-name/'，注意结尾斜杠不能少 - GitHub Pages 设置里，Source 必须选
GitHub Actions，不能选main branch /docs folder—— 后者绕过 VitePress 构建流程，直接扔静态文件，base配置无效 - CI 脚本里构建命令应为
vitepress build docs，不是vitepress build，否则它找不到入口docs/index.md
真正麻烦的从来不是怎么写配置，而是哪一步没按 VitePress 的约定来：比如 base 忘加斜杠、docs:dev 被当成一次性命令关掉了终端、或者以为装了插件就能自动适配 frontmatter——它不会，VitePress 的解析逻辑完全独立于编辑器。
