如何处理Vite SSG中的动态路由？

Question

在使用 Vite 进行静态站点生成（SSG）时，如何正确处理动态路由（如 `/post/:id`）是一个常见挑战。Vite 默认的构建机制不会自动捕获动态路径所需的全部数据，导致预渲染失败或页面缺失。开发者常问：**如何在 Vite SSG 中有效配置并抓取动态路由所需的数据，以确保所有路径都能正确生成静态页面？** 这个问题涉及 Vue Router 的动态路由配置、构建时的路径收集机制以及与后端 API 或本地 Markdown 文件等数据源的集成方式。解决它通常需要结合 `vite-plugin-ssg` 插件提供的 `routes` 配置或自定义爬虫逻辑，确保构建系统能识别并生成所有必要的 HTML 页面。

Answer 1

一、Vite SSG 中动态路由处理的挑战

Vite 默认使用基于文件系统的路由（如 Vue 项目中使用 <src>/pages/ 目录结构），但当涉及到动态路径如 /post/:id 时，无法自动识别所有可能的参数值。这导致在构建静态页面时，某些动态路径未被生成，从而出现 404 页面。

问题的核心在于：如何在构建阶段获取所有需要渲染的动态路径？

二、Vue Router 的动态路由配置

在 Vue 项目中，通常通过 Vue Router 定义动态路由：

import { createRouter, createWebHistory } from 'vue-router'
import PostDetail from '../views/PostDetail.vue'

const routes = [
  {
    path: '/post/:id',
    name: 'PostDetail',
    component: PostDetail
  }
]

const router = createRouter({
  history: createWebHistory(),
  routes
})

export default router
  

上述配置仅定义了路由模板，但没有提供具体的 :id 值集合。

三、vite-plugin-ssg 插件与 SSG 构建机制

Vite 本身不直接支持 SSG，需借助 vite-plugin-ssg 插件实现。该插件在构建时会根据提供的路由列表进行预渲染。

关键配置项：routes，用于指定所有应被生成的路径。

四、解决方案一：手动注入动态路径

适用于数据量较小的情况，例如从本地 JSON 或 Markdown 文件读取文章 ID 列表。

// vite.config.js
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ssr from 'vite-plugin-ssg'

// 获取所有 post id
function getPostIds() {
  return ['1', '2', '3'] // 可替换为从文件或 API 获取
}

export default defineConfig({
  plugins: [
    vue(),
    ssr({
      routes: ['/'].concat(getPostIds().map(id => `/post/${id}`))
    })
  ]
})
  

这种方式可确保所有 /post/:id 路径都被正确生成。

五、解决方案二：从远程 API 获取路径

若数据源来自后端接口，则可在构建前调用 API 获取所有 ID。

async function fetchPostIdsFromAPI() {
  const res = await fetch('https://api.example.com/posts')
  const posts = await res.json()
  return posts.map(p => p.id)
}

export default defineConfig(async () => {
  const ids = await fetchPostIdsFromAPI()

  return {
    plugins: [
      vue(),
      ssr({
        routes: ['/'].concat(ids.map(id => `/post/${id}`))
      })
    ]
  }
})
  

注意：由于 Vite 配置默认是同步的，必须将整个 vite.config.js 导出为异步函数。

六、解决方案三：自定义爬虫逻辑

对于大型站点，可编写一个简单的爬虫程序，在构建时抓取首页或其他页面中的链接，并提取所有动态路径。

• 使用 cheerio 解析 HTML 页面内容
• 使用 node-fetch 请求页面

流程图如下：

graph TD
      A[启动构建] --> B{是否存在动态路由?}
      B -- 是 --> C[执行爬虫脚本]
      C --> D[解析 HTML 获取所有 /post/:id 路径]
      D --> E[将路径写入缓存文件]
      E --> F[配置 vite-plugin-ssg 使用缓存路径]
      F --> G[开始预渲染]
      B -- 否 --> G

七、结合 Markdown 数据源生成路径

若站点内容来自本地 Markdown 文件，可通过遍历目录获取所有文件名作为 ID。

文件路径	ID 值
posts/1.md	1
posts/2.md	2
posts/3.md	3

代码示例：

import fs from 'fs'
import path from 'path'

function getMarkdownIds() {
  const dir = path.resolve(__dirname, './posts')
  return fs.readdirSync(dir).map(f => f.replace('.md', ''))
}
  

八、构建优化建议

1. 避免每次构建都调用远程 API，建议缓存结果并设置更新策略
2. 对大规模数据，考虑分页生成或增量构建
3. 使用 process.env.VITE_SSR 区分客户端与服务端逻辑
4. 测试时启用 ssgOptions.onFinished 回调确认生成结果