如何在VSCode中配置Node环境以运行VitePress静态文档系统

很多人以为在VSCode里跑VitePress需要专门配置Node环境，其实没那么复杂。说白了，VSCode本身并不“配置”Node——它只是复用你系统里已有的Node和包管理器。你真正要解决的是三个问题：让终端能正确调用vitepress命令、让项目识别ESM模块、以及别让插件干扰Markdown渲染。只要这三个点对齐了，剩下的基本都是顺理成章的事。

终端里执行 vitepress dev 报 command not found

这个错误其实跟VSCode没半毛钱关系，纯粹是终端找不到vitepress这个可执行文件。常见的原因就那么几种：

• 没全局安装vitepress：VitePress是本地开发依赖，不是全局工具。你该用pnpm add -D vitepress（或npm install --save-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"的script。直接运行pnpm docs:dev比手动拼命令更安全，能避免路径错位的问题。

require is not defined 或 import 报错

这是模块系统不匹配的典型症状——VitePress要求ESM，但VSCode默认按CommonJS去解析.vitepress/config.js。解决起来其实就三步：

• 在项目根目录的package.json里加上"type": "module"，否则import会被降级处理，而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文件里