常见问题 FAQ

VitePress 使用中最常见的问题速查。更详细的问题和解决方案请查阅 开发 FAQ 专题。

安装与环境

Node.js 版本要求？

VitePress 需要 Node.js 18+，建议使用 LTS 版本。

node --version  # 确保 >= 18
npx vitepress --version

推荐使用 nvm 管理 Node.js 版本：

nvm install --lts
nvm use --lts

安装 VitePress 失败？

常见原因及解决方案：

问题	原因	解决方案
EACCES 权限错误	npm 全局目录权限不足	使用 npx 代替全局安装
网络超时	npm 官方源国内访问慢	使用镜像源：npm config set registry https://registry.npmmirror.com
peerDependencies 警告	Vue 版本不匹配	确保 vue 版本为 3.x
锁文件冲突	package-lock.json 不一致	删除 node_modules 和 package-lock.json 后重装

推荐的项目初始化方式？

# 方式一：使用初始化向导（推荐）
npm init
npx vitepress init

# 方式二：手动安装
npm install vitepress -D
npm install vue -D

配置相关

如何设置中文？

// .vitepress/config.mts
export default defineConfig({
  lang: 'zh-CN',
  description: '中文描述',
  themeConfig: {
    docFooter: { prev: '上一页', next: '下一页' },
    outlineTitle: '目录',
    lastUpdated: { text: '最后更新于' }
  }
})

如何修改主题颜色？

/* .vitepress/theme/styles/custom.css */
:root {
  --vp-c-brand-1: #6366f1;
  --vp-c-brand-2: #818cf8;
  --vp-c-brand-3: #a5b4fc;
}

/* 暗色模式 */
html.dark {
  --vp-c-brand-1: #818cf8;
  --vp-c-brand-2: #6366f1;
  --vp-c-brand-3: #4f46e5;
}

如何隐藏侧边栏/导航栏？

---
sidebar: false   # 隐藏侧边栏
navbar: false    # 隐藏导航栏
---

或针对特定路由全局配置：

export default defineConfig({
  themeConfig: {
    sidebar: {
      '/guide/': [...],
      '/about': 'false'  // /about 路径隐藏侧边栏
    }
  }
})

如何启用搜索？

export default defineConfig({
  themeConfig: {
    search: {
      provider: 'local'  // 或 'algolia'
    }
  }
})

更多搜索方案请参考 搜索服务。

如何配置导航栏和侧边栏？

export default defineConfig({
  themeConfig: {
    nav: [
      { text: '指南', link: '/guide/' },
      { text: 'API', link: '/api/' },
      { text: '更多', items: [
        { text: 'GitHub', link: 'https://github.com/...' }
      ]}
    ],
    sidebar: {
      '/guide/': [
        { text: '入门', items: [
          { text: '快速开始', link: '/guide/getting-started' },
          { text: '安装', link: '/guide/installation' }
        ]}
      ]
    }
  }
})

详细配置请参考 导航栏配置 和 侧边栏配置。

Markdown 与内容

如何在 Markdown 中使用 Vue 组件？

<script setup>
import MyComponent from './MyComponent.vue'
</script>

<MyComponent />

注意

Vue 组件需要在 .vitepress/theme/index.ts 中全局注册，或通过 <script setup> 局部导入。

Markdown 语法不生效？

常见原因：

1. 缩进问题：代码块和列表的缩进必须正确
2. 空行缺失：块级元素之间需要空行分隔
3. 特殊字符未转义：<、> 等字符需要用反引号包裹
4. frontmatter 格式错误：确保 --- 包裹正确

代码块高亮不正确？

确保指定了语言类型，并检查是否需要安装额外的语法高亮包：

```typescript
const greeting: string = 'Hello'
```

VitePress 使用 Shiki 进行语法高亮，支持的语言列表参见 Shiki 支持语言。

构建与部署

构建失败？

按顺序排查：

1. Node.js 版本：确保 >= 18
2. 清除缓存：rm -rf node_modules package-lock.json && npm install
3. 检查 Markdown：语法错误会导致构建失败
4. 检查组件导入：路径是否正确，SSR 兼容性
5. 查看完整日志：npm run docs:build 2>&1 | tee build.log

构建内存不足？

# 增加内存限制
NODE_OPTIONS="--max-old-space-size=4096" npm run docs:build

# 在 package.json 中固定配置
{
  "scripts": {
    "docs:build": "NODE_OPTIONS='--max-old-space-size=4096' vitepress build docs"
  }
}

构建速度慢？

优化方式	说明
减少页面数量	大型站点可考虑拆分
排除不必要文件	配置 srcExclude
优化图片资源	使用压缩后的图片
增量构建	仅构建变更的页面

export default defineConfig({
  srcExclude: ['**/draft/**', '**/private/**'],
  cacheDir: '.vitepress/cache'
})

部署后页面 404？

常见原因：

1. SPA 路由问题：服务器未配置回退到 index.html
2. base 路径错误：部署到子路径需要设置 base

// 部署到 https://example.com/docs/
export default defineConfig({
  base: '/docs/'
})

Nginx 配置示例：

location / {
  try_files $uri $uri/ /index.html;
}

主题与样式

如何切换暗色模式？

VitePress 默认主题内置暗色模式切换，用户可通过导航栏的切换按钮操作。

如需强制指定模式：

export default defineConfig({
  appearance: 'dark'  // 强制暗色，'force-dark' 可禁止切换
})

如何自定义首页？

---
layout: home
hero:
  name: VitePress
  text: 学习指南
  tagline: 从零开始学习 VitePress
  actions:
    - theme: brand
      text: 快速开始
      link: /guide/
features:
  - title: 简洁优先
    details: 以 Markdown 为中心的项目结构
  - title: Vue 驱动
    details: 在 Markdown 中使用 Vue 组件
---

样式不生效？

排查步骤：

1. 检查 CSS 文件是否在 theme/index.ts 中导入
2. 确认 scoped 样式不会影响子组件
3. 检查 CSS 选择器优先级
4. 使用浏览器开发者工具检查元素样式

组件与 SSR

"window is not defined" 错误？

组件在 SSR 阶段被渲染，浏览器 API 不可用：

<!-- 方式一：onMounted -->
<script setup>
import { onMounted, ref } from 'vue'
const isClient = ref(false)
onMounted(() => { isClient.value = true })
</script>

<template>
  <div v-if="isClient">客户端渲染内容</div>
</template>

<!-- 方式二：ClientOnly 组件 -->
<ClientOnly>
  <BrowserOnlyComponent />
</ClientOnly>

<!-- 方式三：动态导入 -->
<script setup>
import { defineAsyncComponent } from 'vue'
const AsyncComp = defineAsyncComponent(() => import('./BrowserOnly.vue'))
</script>

组件样式在 SSR 中不一致？

确保样式使用 VitePress 的 CSS 变量而非硬编码颜色值：

/* ✅ 正确 */
.text { color: var(--vp-c-text-1); }

/* ❌ 可能不一致 */
.text { color: #213547; }

性能与优化

页面加载慢？

优化方向	方法
图片优化	使用 WebP 格式，添加 loading="lazy"
代码分割	大型组件使用异步导入
减少依赖	检查是否有不必要的 npm 包
预构建优化	配置 vite.optimizeDeps.include

站点体积过大？

export default defineConfig({
  vite: {
    build: {
      rollupOptions: {
        output: {
          manualChunks: {
            'vue-vendor': ['vue', 'vue-router']
          }
        }
      }
    }
  }
})

更多问题

以上仅列出最高频问题，完整 FAQ 涵盖 25+ 分类、200+ 问题：

• 开发 FAQ 专题 — 安装配置、Markdown、主题、路由、搜索、部署、PWA、多语言、性能、SEO、安全等
• VitePress 官方文档
• GitHub Issues
• GitHub Discussions