项目结构解析

了解 VitePress 项目的标准结构，有助于你更好地组织文档内容。

基础目录结构

一个典型的 VitePress 项目结构如下：

project/
├── docs/                      # 文档根目录
│   ├── .vitepress/            # VitePress 配置目录
│   │   ├── config.mts         # 主配置文件
│   │   ├── theme/             # 主题定制目录
│   │   │   ├── index.ts       # 主题入口文件
│   │   │   └── style.css      # 主题样式
│   │   └── cache/             # 构建缓存（自动生成）
│   ├── public/                # 静态资源目录
│   │   └── images/            # 图片资源
│   ├── guide/                 # 指南文档
│   │   ├── index.md
│   │   └── getting-started.md
│   ├── api/                   # API 文档
│   │   └── index.md
│   └── index.md               # 网站首页
├── node_modules/              # 依赖包
├── package.json               # 项目配置
└── package-lock.json          # 依赖锁定文件

核心目录说明

.vitepress/

VitePress 的核心配置目录，存放所有配置相关文件。

重要文件

• config.mts：主配置文件，配置站点标题、导航、侧边栏等
• theme/：自定义主题相关文件

public/

存放静态资源，这些文件会直接复制到输出目录：

public/
├── images/
│   └── logo.png
├── favicon.ico
└── robots.txt

访问方式：/images/logo.png

docs/ 下的 Markdown 文件

每个 .md 文件对应一个路由：

文件路径	URL 路径
docs/index.md	/
docs/guide/index.md	/guide/
docs/guide/getting-started.md	/guide/getting-started

配置文件详解

config.mts 基础结构

import { defineConfig } from 'vitepress'

export default defineConfig({
  // 站点级配置
  title: '站点标题',
  description: '站点描述',
  lang: 'zh-CN',
  
  // 主题配置
  themeConfig: {
    nav: [...],      // 导航栏
    sidebar: {...},  // 侧边栏
    footer: {...}    // 页脚
  }
})

主题目录结构

当你需要自定义主题时，theme/ 目录的结构：

theme/
├── index.ts          # 主题入口
├── style.css         # 全局样式
├── Layout.vue        # 自定义布局组件
└── components/       # 自定义组件
    ├── Hero.vue
    └── Footer.vue

主题入口文件

// theme/index.ts
import DefaultTheme from 'vitepress/theme'
import './style.css'

export default {
  extends: DefaultTheme,  // 继承默认主题
  // 自定义扩展...
}

构建输出目录

运行 npm run docs:build 后，默认生成：

docs/.vitepress/dist/
├── assets/
│   ├── index.js
│   └── index.css
├── guide/
│   ├── index.html
│   └── getting-started.html
├── index.html
└── public/           # public 目录内容

推荐的项目组织方式

按功能模块划分

docs/
├── guide/            # 入门指南
├── api/              # API 参考
├── examples/         # 示例代码
├── faq/              # 常见问题
└── changelog/        # 更新日志

多语言项目结构

docs/
├── .vitepress/
│   └── config.mts
├── zh/               # 中文文档
│   └── guide/
├── en/               # 英文文档
│   └── guide/
└── index.md

忽略文件配置

VitePress 默认忽略以 . 开头的目录和文件。你可以通过配置控制：

不需要构建的文件

docs/
├── .vitepress/       # 自动忽略
├── drafts/           # 草稿目录（通过 sidebar 配置排除）
├── private/          # 私有文档
└── public/           # 静态资源，直接复制

在 sidebar 中排除页面

如果某些页面不需要出现在侧边栏，只需不在 sidebar 配置中添加即可，页面仍然可以通过 URL 直接访问。

常见问题

文件名用什么格式？

推荐使用小写字母和连字符：

推荐写法	不推荐写法
getting-started.md	GettingStarted.md
api-reference.md	API Reference.md
vue-components.md	vue_components.md

图片应该放在哪里？

• 文档引用的图片 → docs/public/images/（通过 /images/xxx.png 访问）
• 主题使用的图片 → docs/.vitepress/theme/assets/（通过 import 引入）
• 首页 Hero 图片 → docs/public/（通过 frontmatter 引用）

config.mts 和 config.ts 有什么区别？

• .mts — 明确标识为 ES Module，VitePress 推荐
• .ts — 也支持，但需要 package.json 中配置 "type": "module"

如何组织大型项目的配置？

对于配置较多的项目，可以将配置拆分为多个文件：

.vitepress/
├── config.mts         # 主配置（合并各部分）
├── config/
│   ├── nav.ts         # 导航配置
│   ├── sidebar.ts     # 侧边栏配置
│   └── head.ts        # Head 标签配置
└── theme/
    ├── index.ts
    └── ...

// config.mts
import { nav } from './config/nav'
import { sidebar } from './config/sidebar'
import { head } from './config/head'

export default defineConfig({
  head,
  themeConfig: {
    nav,
    sidebar
  }
})

下一步

了解了项目结构后，让我们 创建第一个页面。