许多开发者误以为在VSCode中运行VitePress必须单独配置Node环境，但其实操作并不复杂。实际上，VSCode只是复用系统已有的Node和包管理器，无需额外配置。关键只需解决三个核心问题：确保终端能正确调用vitepress命令、让项目识别ESM模块、以及避免插件干扰Markdown渲染。只要这三方面处理得当，其余步骤便能顺利推进。
终端执行 vitepress dev 时遇到 command not found 错误
这个错误其实与VSCode无关，根本原因是终端无法找到vitepress可执行文件。常见原因如下：
- 未全局安装
vitepress：VitePress是本地开发依赖而非全局工具。应使用pnpm add -D vitepress（或npm install --sa ve-dev vitepress）将其安装到项目中，并通过pnpm vitepress dev启动，而不是直接运行vitepress dev。这是新手最容易踩的坑。 pnpm或npm命令本身不可用：首先确认node -v版本是否≥18，然后检查pnpm -v是否有输出。macOS/Linux用户可能在VSCode终端中需要先执行source ~/.zshrc刷新PATH，Windows用户则需检查环境变量中是否包含pnpm安装路径。- 启动脚本配置错误：
package.json中应包含类似"docs:dev": "vitepress dev docs"的脚本。直接运行pnpm docs:dev比手动输入命令更可靠，可避免路径错误。
require is not defined 或 import 报错如何解决
这是模块系统不匹配的典型表现——VitePress要求使用ESM，但VSCode默认按CommonJS解析.vitepress/config.js。解决方案只需三步：
- 在项目根目录的
package.json中添加"type": "module"，否则import会被降级为CommonJS，而require()在浏览器环境下不存在。 - 如果使用
config.ts，务必安装@types/node，并确保VSCode右下角显示的TypeScript版本与项目中node_modules/typescript一致（点击即可切换）。 - 不要自作主张将
config.js改为config.cjs——VitePress官方并不保证require()在所有构建阶段均可使用，强行修改后缀只会引发更多兼容性问题。
Markdown 编辑卡顿、预览不生效，以及
VSCode本身无法直接解析VitePress的Markdown扩展语法（如frontmatter、自定义容器、内联Vue脚本），需要借助插件。但选错插件反而比不安装更麻烦。
- 必须安装
Volar（而非Vetur）：它是Vue 3 + Vite生态的官方语言服务器，唯一能解析.md文件中的