MPA 模式

MPA（Multi-Page Application）模式是 VitePress 提供的一种构建方式，适用于需要避免 SSR 兼容性问题的场景。

什么是 MPA 模式

MPA 模式下，VitePress 会：

• 为每个页面生成独立的 HTML 文件
• 不使用服务端渲染（SSR）
• 每个页面独立加载和执行

与 SSR 模式的区别

特性	SSR 模式	MPA 模式
构建方式	服务端渲染	静态生成
首屏加载	快	较慢
SEO	完全支持	完全支持
SSR 兼容性	需要注意	无需关注
构建速度	较快	较慢
输出体积	较小	较大

启用 MPA 模式

在配置文件中设置：

// docs/.vitepress/config.mts
export default defineConfig({
  // 启用 MPA 模式
  mpa: true
})

适用场景

适合 MPA 模式

1. 使用不兼容 SSR 的第三方库

   • 大量使用 window、document 的库
   • 没有 SSR 支持的 UI 组件库

2. 简单的文档站点

   • 不需要复杂的交互
   • 页面之间独立性强

3. 调试 SSR 问题

   • 快速定位是否为 SSR 导致的问题
   • 作为排查问题的临时方案

不适合 MPA 模式

1. 需要快速首屏加载

   • SSR 模式首屏渲染更快
   • 用户体验要求高的站点

2. 大量页面

   • 构建时间会显著增加
   • 输出体积较大

3. 需要共享运行时状态

   • 页面间无法共享状态
   • 需要通过 URL 参数或存储传递数据

配置示例

基础配置

// docs/.vitepress/config.mts
import { defineConfig } from 'vitepress'

export default defineConfig({
  mpa: true,
  
  title: '我的文档',
  description: '使用 MPA 模式的文档站点',
  
  themeConfig: {
    // 主题配置
  }
})

结合其他配置

export default defineConfig({
  mpa: true,
  
  // 清理 URL
  cleanUrls: true,
  
  // 最后更新时间
  lastUpdated: true,
  
  // 站点地图
  sitemap: {
    hostname: 'https://example.com'
  }
})

MPA 模式的注意事项

1. 页面导航

MPA 模式下，页面导航会触发完整的页面刷新：

<!-- 这会导致完整页面刷新 -->
<a href="/guide/installation">安装指南</a>

<!-- 使用 Vue Router 的导航也会刷新页面 -->
<RouterLink to="/guide/installation">安装指南</RouterLink>

2. 状态管理

页面间无法共享状态：

<script setup>
import { ref } from 'vue'

// 这个状态在页面导航后会丢失
const counter = ref(0)
</script>

如需持久化状态，使用 localStorage：

<script setup>
import { ref, watch } from 'vue'

const counter = ref(
  Number(localStorage.getItem('counter') || 0)
)

watch(counter, (val) => {
  localStorage.setItem('counter', String(val))
})
</script>

3. 组件生命周期

每个页面都是独立的 Vue 实例：

<script setup>
import { onMounted, onUnmounted } from 'vue'

onMounted(() => {
  console.log('页面挂载')
})

onUnmounted(() => {
  // 注意：MPA 模式下可能不会触发
  console.log('页面卸载')
})
</script>

迁移指南

从 SSR 模式迁移

1. 添加 mpa 配置

export default defineConfig({
  mpa: true
})

2. 移除 SSR 相关代码

<!-- 之前 -->
<script setup>
if (!import.meta.env.SSR) {
  // 客户端代码
}
</script>

<!-- 之后 -->
<script setup>
// 可以直接使用浏览器 API
console.log(window.innerWidth)
</script>

3. 测试所有页面

确保页面导航正常工作。

迁移回 SSR 模式

1. 移除 mpa 配置

export default defineConfig({
  // mpa: true, // 删除这行
})

2. 处理 SSR 兼容性

参考 SSR 兼容性 文档处理兼容性问题。

性能对比

构建性能

# SSR 模式
npm run build  # ~15s

# MPA 模式
npm run build  # ~45s（页面较多时更慢）

运行时性能

指标	SSR 模式	MPA 模式
首屏 LCP	~1.2s	~2.0s
TTI	~1.5s	~2.5s
页面切换	~50ms	~300ms

最佳实践

1. 按需选择

• 优先使用 SSR 模式
• 仅在 SSR 兼容性问题时考虑 MPA

2. 优化构建

export default defineConfig({
  mpa: true,
  
  vite: {
    build: {
      // 增加 chunk 大小警告阈值
      chunkSizeWarningLimit: 1500,
      
      // 优化分包
      rollupOptions: {
        output: {
          manualChunks: {
            'vendor': ['vue']
          }
        }
      }
    }
  }
})

3. 预加载优化

export default defineConfig({
  mpa: true,
  
  head: [
    // 预加载关键资源
    ['link', { rel: 'prefetch', href: '/guide/installation.html' }]
  ]
})

常见问题

页面导航闪烁

MPA 模式下页面导航会有短暂的白屏，可以通过添加过渡动画缓解：

/* docs/.vitepress/theme/custom.css */
html {
  transition: opacity 0.2s ease;
}

html.navigating {
  opacity: 0;
}

构建时间过长

减少页面数量或使用增量构建：

export default defineConfig({
  mpa: true,
  
  // 缓存配置
  cacheDir: '.vitepress/cache'
})

相关资源

• SSR 兼容性
• 构建优化
• 性能优化

下一步

• 了解 创建第一个页面
• 学习 基础功能配置