快速开始
在线尝试
可以直接在 StackBlitz 上进行在线尝试。
安装
前置准备
VitePress 可以单独使用，也可以安装到现有项目中。在这两种情况下，都可以使用以下方式安装它：
$ npm add -D @10coding/vitepress-react@next$ pnpm add -D @10coding/vitepress-react@next$ yarn add -D @10coding/vitepress-react@next$ bun add -D @10coding/vitepress-react@next注意
VitePress 是仅 ESM 的软件包。不要使用 require() 导入它，并确保最新的 package.json 包含 "type": "module"，或者更改相关文件的文件扩展名，例如 .vitepress-react/config.js 到 .mjs/.mts。更多详情请参考 Vite 故障排除指南。此外，在异步 CJS 上下文中，可以使用 await import('@10coding/vitepress-react') 代替。
安装向导
VitePress 附带一个命令行设置向导，可以帮助你构建一个基本项目。安装后，通过运行以下命令启动向导：
$ npx vitepress-react init$ pnpm vitepress-react init$ yarn vitepress-react init$ bun vitepress-react init将需要回答几个简单的问题：
┌ Welcome to VitePress!
│
◇ Where should VitePress initialize the config?
│ ./docs
│
◇ Where should VitePress look for your markdown files?
│ ./docs
│
◇ Site title:
│ My Awesome Project
│
◇ Site description:
│ A VitePress Site
│
◇ Theme:
│ Default Theme
│
◇ Use TypeScript for config and theme files?
│ Yes
│
◇ Add VitePress npm scripts to package.json?
│ Yes
│
◇ Add a prefix for VitePress npm scripts?
│ Yes
│
◇ Prefix for VitePress npm scripts:
│ docs
│
└ Done! Now run pnpm run docs:dev and start writing.React 作为依赖
react / react-dom(React 19)是本包的必需 peerDependencies:站点运行时(hydration)与 md 页面编译产物的 JSX runtime 都要从宿主根解析 react,而 strict pnpm 只会把宿主直接声明的依赖放在根上——所以宿主项目必须能解析到它们。
- npm(≥ 7):安装本包时会自动安装 peer,上面一条命令即可。
- pnpm / yarn:需要显式安装:
pnpm add -D @10coding/vitepress-react react react-dom(pnpm 默认不自动安装 peer)。 - 用
vitepress-react init搭建的站点会自动把@10coding/vitepress-react、react、react-dom写入devDependencies;之后只需pnpm install/npm install即可启动,无需再手动添加。
文件结构
如果正在构建一个独立的 VitePress 站点，可以在当前目录 (./) 中搭建站点。但是，如果在现有项目中与其他源代码一起安装 VitePress，建议将站点搭建在嵌套目录 (例如 ./docs) 中，以便它与项目的其余部分分开。
假设选择在 ./docs 中搭建 VitePress 项目，生成的文件结构应该是这样的：
.
├─ docs
│ ├─ .vitepress-react
│ │ └─ config.js
│ ├─ api-examples.md
│ ├─ markdown-examples.md
│ └─ index.md
└─ package.jsondocs 目录作为 VitePress 站点的项目根目录。.vitepress-react 目录是 VitePress 配置文件、开发服务器缓存、构建输出和可选主题自定义代码的位置。
提示
默认情况下，VitePress 将其开发服务器缓存存储在 .vitepress-react/cache 中，并将生产构建输出存储在 .vitepress-react/dist 中。如果使用 Git，应该将它们添加到 .gitignore 文件中。也可以手动配置这些位置。
配置文件
配置文件 (.vitepress-react/config.js) 让你能够自定义 VitePress 站点的各个方面，最基本的选项是站点的标题和描述：
export default {
// 站点级选项
title: 'VitePress',
description: 'Just playing around.',
themeConfig: {
// 主题级选项
}
}还可以通过 themeConfig 选项配置主题的行为。有关所有配置选项的完整详细信息，请参见配置参考。
源文件
.vitepress-react 目录之外的 Markdown 文件被视为源文件。
VitePress 使用 基于文件的路由：每个 .md 文件将在相同的路径被编译成为 .html 文件。例如，index.md 将会被编译成 index.html，可以在生成的 VitePress 站点的根路径 / 进行访问。
VitePress 还提供了生成简洁 URL、重写路径和动态生成页面的能力。这些将在路由指南中进行介绍。
启动并运行
该工具还应该将以下 npm 脚本注入到 package.json 中：
{
...
"scripts": {
"docs:dev": "vitepress-react dev docs",
"docs:build": "vitepress-react build docs",
"docs:preview": "vitepress-react preview docs"
},
...
}docs:dev 脚本将启动具有即时热更新的本地开发服务器。使用以下命令运行它：
$ npm run docs:dev$ pnpm run docs:dev$ yarn docs:dev$ bun run docs:dev除了 npm 脚本，还可以直接调用 VitePress：
$ npx vitepress-react dev docs$ pnpm vitepress-react dev docs$ yarn vitepress-react dev docs$ bun vitepress-react dev docs更多的命令行用法请参见 CLI 参考。
开发服务应该会运行在 http://localhost:5173 上。在浏览器中访问 URL 以查看新站点的运行情况吧！
下一步
想要进一步了解 Markdown 文件是怎么映射到对应的 HTML，请继续阅读路由指南。
要了解有关可以在页面上执行的操作的更多信息，例如编写 Markdown 内容或使用 React 组件/表达式，请参见指南的“写作”部分。一个好的起点是在 Markdown 中使用 React 与 Markdown 扩展。
要探索默认文档主题提供的功能，请查看默认主题配置参考。
文档成形以后，务必阅读部署指南。