VitePress 最新版默认采用 ESM 格式，若项目根目录缺少 type: "module" 声明，Node.js 会以 CommonJS 模式加载配置文件，导致 require() 尝试加载 ESM 包（如 vitepress）而报错。本文详解如何快速修复该问题，并确保项目长期兼容。
vitepress 最新版默认采用 esm 格式，若项目根目录缺少 `type: "module"` 声明，node.js 会以 commonjs 模式加载配置文件，导致 `require()` 尝试加载 esm 包（如 vitepress）而报错。本文详解如何快速修复该问题，并确保项目长期兼容。
当你使用 pnpm create vitepress@latest 初始化项目后，执行 pnpm run docs:dev 却遇到如下典型错误：
"vitepress" resolved to an ESM file. ESM file cannot be loaded by `require`.
该错误本质是 模块系统不匹配：VitePress v1.0+ 已全面转向纯 ESM（Export-only），而 Node.js 默认以 CommonJS 模式运行脚本（尤其在加载 .vitepress/config.js 时）。当 Vite 的插件（如 externalize-deps）尝试通过 require() 解析 vitepress 包时，就会因 ESM 不支持 require 而崩溃。
✅ 根本解决方案：在项目根目录的 package.json 中显式声明模块类型
只需一行修改，即可彻底解决：
{
"name": "my-vitepress-site",
"version": "1.0.0",
"type": "module", // ← 关键：启用 ES Module 模式
"scripts": {
"docs:dev": "vitepress dev docs",
"docs:build": "vitepress build docs",
"docs:serve": "vitepress serve docs"
},
"dependencies": {
"vitepress": "^1.3.0"
}
}? 注意："type": "module" 必须位于 项目根目录的 package.json（即与 pnpm-lock.yaml 同级），而非 docs/ 子目录下。VitePress 的 CLI 启动逻辑依赖于该顶层配置来决定 Node.js 的模块解析行为。
? 额外验证建议（推荐）
- 确认 Node.js 版本：需 ≥ v18.12.0（推荐 v20+），因早期版本对 ESM 支持不完善；
- 检查配置文件扩展名：.vitepress/config.js 可继续使用 .js 后缀（只要 package.json 声明了 "type": "module"），但若希望更明确，也可重命名为 config.mjs；
-
避免混用 require()：在 config.ts 或 config.js 中，所有导入必须使用 import 语法，禁止出现 require('vitepress') —— 正确写法为：
import { defineConfig } from 'vitepress' export default defineConfig({ /* ... */ })
⚠️ 常见误区提醒
- ❌ 不要试图降级 vitepress 到旧版（如 0.x）来绕过问题——这将失去新功能、安全更新及官方维护；
- ❌ 不要手动 patch node_modules 或修改 esbuild 配置——违背工程规范且不可持续；
- ✅ 此方案符合 Vite 官方 ESM 兼容指南，也是 VitePress 文档隐式要求的最佳实践。
完成修改后，重新运行命令即可正常启动：
pnpm run docs:dev # ✔️ Success: VitePress dev server now running at http://localhost:5173
总结："type": "module" 是现代 Vite/VitePress 项目的标准基础设施配置，它不仅解决当前报错，更为后续使用 TypeScript、自定义插件、SSG 构建等高级能力奠定基础。建议所有新建 VitePress 项目初始化后第一时间添加该字段。
