在现有 Vue3 + Vite + TypeScript 项目中使用 Vike 实现静态预渲染（SSG）
背景简介
在一个已经运行良好的 Vue3 + Vite + TypeScript 项目中，为了满足 SEO 优化需求，需要将少量关键页面预渲染为静态 HTML。相比于服务端渲染（SSR），静态生成（SSG）对项目结构简单、页面数量有限的场景更加轻量。本文示范如何基于 Vite 插件 Vike（原 vite‑plugin‑ssr）快速为现有项目添加静态预渲染支持。
1. 安装并配置 Vike
使用 npm 或 yarn 安装插件：
npm install vike --save-dev # 或 yarn add vike --dev `在
vite.config.ts中引入并启用预渲染：import { defineConfig } from 'vite' import vue from '@vitejs/plugin-vue' import vike from 'vike/plugin' export default defineConfig({ plugins: [ vue(), vike({ prerender: true }) // 若只需 SSR，可去掉 prerender 选项 ] })
2. 创建并填充 renderer 目录
- 在项目根目录下与
src同级创建renderer/文件夹。 参考官方示例（vike-with-pinia，boilerplate-vue-ts），将以下关键文件拷贝过来：
config.tsonBeforeRender.tsonRenderClient.tsonRenderHtml.tsapp.tstypes.tsusePageContext.ts
2.1 客户端渲染逻辑（onRenderClient.ts）
在这里编写浏览器端逻辑（如检测不同浏览器环境等）。
2.2 服务端 HTML 模板（onRenderHtml.ts）
根据 pageContext.urlPathname 判断不同路由，动态生成 <title>、<meta> 信息，确保中文不乱码请添加：
<meta charset="UTF-8" />
示例：
const documentHtml = escapeInject`<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8" />
<title>${title}</title>
</head>
<body>
<div id="app">${stream}</div>
</body>
</html>`
2.3 应用入口（app.ts）
在 SSG/SSR 模式下，main.ts 和原有 index.html 不再生效，需在 app.ts：
- 创建 SSR 应用：
createSSRApp - 引入 Pinia 并使用
pinia-plugin-persistedstate - 处理 Element Plus 的水合（hydration）错误
3. 重命名视图目录与页面组件
- 将
src/views重命名为src/pages，Vike 会自动根据此目录生成路由。 每个页面文件夹内改为
+Page.vue：src/pages/ ├─ about/ │ └─ +Page.vue // 对应 /about ├─ blog/ │ └─ +Page.vue // 对应 /blog └─ _error/ └─ +Page.vue // 404 或通配原先使用
vue-router的跳转改为：window.location.href = '/about'
4. 客户端专属组件（Client‑only）
对于依赖 window、localStorage 等浏览器 API 的组件，需要仅在客户端渲染：
<template>
<ClientOnly :load="() => import('@/components/MyBrowserOnly.vue')" />
</template>
ClientOnly 组件可参考 Vike 官方仓库示例。
5. 处理外部依赖排除问题
如果打包时报 Element Plus 等包被当外部依赖排除，可在 vite.config.ts 中新增：
export default defineConfig({
// …plugins 配置
ssr: {
noExternal: ['element-plus']
}
})
6. 构建与发布
运行预渲染打包：
npm run build- 在
dist/client/目录下会生成所有静态 HTML 与资源，直接部署到静态服务器即可，无需额外服务器逻辑。
7. 建议参考官方示例进行修改
官方示例
vikejs
小结
- 使用 Vike 可以无缝为已有 Vue3 + Vite + TS 项目添加 SSG 功能，极大提升 SEO 效果与首屏性能。
- 通过动态路由判断，可为每个页面自定义
<title>、<meta>信息。 - 注意重命名
pages目录、客户端组件和外部依赖配置，确保打包顺利。
参考
https://juejin.cn/post/7341593721099436072
https://blog.csdn.net/qq_34988304/article/details/135835945
https://juejin.cn/post/7483329722497581082
https://vike.dev/
- 本文标签： vue3 vike vite
- 本文链接： https://code.itptg.com/article/16
- 版权声明： 本文由老魏原创发布，转载请遵循《署名-非商业性使用-相同方式共享 4.0 国际 (CC BY-NC-SA 4.0)》许可协议授权
