prerender-spa-plugin 实战:Vue 2 + Webpack 预渲染静态 HTML 页面指南
prerender-spa-plugin 实战:Vue 2 + Webpack 预渲染静态 HTML 页面指南
本文以仓库中的官方示例 examples/vue2-webpack-simple 为蓝本,完整讲解如何用 prerender-spa-plugin 为 Vue 2 + Webpack 构建的单页应用(SPA)在构建阶段生成静态预渲染 HTML。读完本文,你将掌握该插件的标准接入流程、routes 与渲染时机的配置方法、多路由场景的扩展方式,以及插件底层的工作原理与常见坑点。
一、示例项目概览:预渲染解决了什么问题
该示例的目标正如 examples/vue2-webpack-simple/README.md 所描述的:演示 Vue.js 2.0 与 Webpack 的配合使用,执行构建后,dist/index.html 会被填充为预渲染完成的页面。也就是说,浏览器拿到手的不再是只有一个空 #app 挂载点的空白 HTML,而是已经渲染好内容的静态页面。
预渲染(Prerendering)的本质(见仓库根目录 README.md 的 "What is Prerendering?" 一节):启动一个无头浏览器(headless browser),逐个加载应用的指定路由,把渲染结果保存为静态 HTML 文件,再交给原来的静态文件服务器托管。它不需要改造现有代码、也不需要搭建 SSR 服务端,并且天然兼容 HTML5 history 导航。
它并非万能,根 README 也明确指出了两类不适合的场景:
- 路由数量庞大:几百上千条路由会显著拖慢构建速度(虽然每次更新只需跑一次,但耗时可能很长);
- 动态内容:如果路由内容依赖登录用户或实时数据源,需要准备占位组件,待客户端加载后再替换,否则预渲染出来的内容会显得异常。
二、构建预渲染页面:两个命令搞定
在 examples/vue2-webpack-simple 目录下,按文档给出的步骤执行:
npm install
npm run build
查看 package.json 可以看到,build 脚本实际执行的是:
"build": "cross-env NODE_ENV=production webpack --progress --hide-modules"
关键点在于 NODE_ENV=production:webpack.config.js 中只有生产分支才会挂载 PrerenderSPAPlugin(详见后文)。构建结束后,检查新生成的 dist 目录,里面除了 webpack 打包产物外,还会出现预渲染好的静态页面。
用 http-server 预览预渲染结果
按文档建议,如果还没安装过静态服务器,可全局安装 http-server:
npm install -g http-server
然后在 dist 目录下启动它,并在浏览器访问 http://localhost:8000/(注意末尾的斜杠,这在很多静态服务器的路由匹配中是必须的):
另外,该示例的 package.json 其实已经内置了 http-server 依赖与一条 serve 脚本(http-server ./dist),所以也可以直接执行 npm run serve 来预览,无需全局安装。
此时在浏览器里右键“查看网页源代码”,你看到的将是包含真实 DOM 内容的 HTML,而不是空的 <div id="app"></div>——这正是 SEO 爬虫与社交平台分享卡片抓取器所期望的内容。
三、修改插件配置:routes 数组与 new PrerenderSPAPlugin
文档明确指出:修改 prerender-spa-plugin 配置的位置在 webpack.config.js 的 plugins 区域,找到 new PrerenderSPAPlugin 即可;如果使用了路由或有多个页面需要预渲染,就编辑该配置对象下的 routes 数组。
该示例的 webpack.config.js 在生产分支(第 57 行起)中是这样接入插件的:
if (process.env.NODE_ENV === 'production') {
module.exports.devtool = '#source-map'
module.exports.plugins = (module.exports.plugins || []).concat([
// ... DefinePlugin / HtmlWebpackPlugin 等
new PrerenderSPAPlugin({
staticDir: path.join(__dirname, 'dist'),
routes: [ '/', '/about', '/contact' ],
renderer: new Renderer({
inject: {
foo: 'bar'
},
headless: true,
renderAfterDocumentEvent: 'render-event'
})
})
])
}
注意:README 中称该模板基于 Webpack 3,但仓库内示例的 package.json 实际声明的是
webpack: ^4.29.5与prerender-spa-plugin: ^3.4.0,阅读或复刻时以仓库实际依赖为准。
核心插件选项速查
结合根 README.md 的 "Plugin Options" 表格,new PrerenderSPAPlugin({...}) 支持以下顶层选项:
| 选项 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
staticDir |
String | 是 | 无 | 托管应用静态文件的根目录路径 |
outputDir |
String | 否 | 无(默认等于 staticDir) |
预渲染页面的输出目录 |
indexPath |
String | 否 | staticDir/index.html |
SPA 的入口 index 文件路径(回退文件) |
postProcess |
Function(Object) → Object / Promise | 否 | 无 | 写文件前对每个渲染结果做定制处理 |
minify |
Object | 否 | 无 | 使用 html-minifier 压缩产物 HTML |
server |
Object | 否 | 无 | 内部应用服务器的配置(如 port、proxy) |
renderer |
Renderer 实例或配置对象 | 否 | new PuppeteerRenderer() |
负责实际渲染的渲染器 |
其中 routes 数组中每项即一个待渲染的路由字符串,例如本示例的 [ '/', '/about', '/contact' ]。插件会为每个路由启动无头浏览器访问对应路径,并把渲染后的 HTML 写到 staticDir 下与路由对应的目录中(如 /about → dist/about/index.html)。
四、renderer 与渲染时机:renderAfterDocumentEvent 的配合
本示例的 renderer 配置为 new Renderer({...}),其中 Renderer 即 PrerenderSPAPlugin.PuppeteerRenderer(基于 puppeteer 的默认渲染器)。它并不直接使用根 README 中展示的高级用法那样复杂的完整配置,而是用最简形态演示了 "渲染时机控制" 这一关键机制。
看 src/main.js:
import Vue from 'vue'
import App from './App.vue'
new Vue({
el: '#app',
render: h => h(App),
mounted () {
// You'll need this for renderAfterDocumentEvent.
document.dispatchEvent(new Event('render-event'))
}
})
应用挂载完成后,在 mounted 钩子里主动向 document 派发 render-event 事件;而插件配置中的 renderAfterDocumentEvent: 'render-event' 会让渲染器等待该事件触发后才捕获页面内容。这样能确保捕获到的 HTML 中已经包含 Vue 完成挂载和首屏渲染后的 DOM,而不是脚本尚未执行的空白模板。
PuppeteerRenderer 常用选项
根 README.md 的 renderer 选项表格归纳如下(均为可选):
| 选项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
maxConcurrentRoutes |
Number | 0(不限) | 同时渲染的路由数量上限,可用于把大批量路由拆成小批次 |
inject |
Object | 无 | 注入到页面全局作用域的对象,必须可被 JSON.stringify,默认挂在 window['__PRERENDER_INJECTED'] |
injectProperty |
String | __PRERENDER_INJECTED |
inject 内容挂载到 window 上的属性名 |
renderAfterDocumentEvent |
String | 无 | 等待 document 上触发指定事件后再渲染,如 document.dispatchEvent(new Event('custom-render-trigger')) |
renderAfterElementExists |
String(选择器) | 无 | 等待 document.querySelector 检测到指定元素后再渲染 |
renderAfterTime |
Integer(毫秒) | 无 | 等待固定时长后再渲染(不推荐,见下) |
skipThirdPartyRequests |
Boolean | false |
自动拦截所有第三方请求,可加速页面加载 |
consoleHandler |
Function | 无 | 自定义页面 console.* 处理函数,参数为路由字符串与 Puppeteer ConsoleMessage 对象 |
| 其他 Puppeteer Launch 选项 | 任意 | 无 | 其余参数原样传给 puppeteer.launch(),如 headless: false(显示浏览器窗口,便于调试) |
三种等待方式中,事件驱动与元素检测是最可靠的:异步渲染完成后由应用主动发信号。renderAfterTime 因为依赖固定时长、对网络等耗时不确定的操作容易产生不可靠结果,官方明确不推荐。注意同一时刻只能启用一种 renderAfterX,这是从 v2 到 v3 的刻意调整(见根 README 的 "Additional Changes"),目的是避免歧义。
五、从单页到多路由:扩展预渲染场景
本示例(vue2-webpack-simple)是一个无 vue-router 的单页演示——App.vue 里只有一个 <div id="app"> 根元素,没有任何路由跳转。但它声明的 routes 依然是三个:/、/about、/contact。此时 /about、/contact 会渲染出与首页相同的内容(因为没有路由切换逻辑),只是各自生成独立的静态文件。
更贴近真实生产形态的是配套示例 examples/vue2-webpack-router:它引入了 vue-router,并把路由模式设为 HTML5 history:
const routes = [
{ path: '/', component: Home },
{ path: '/about', component: About },
{ path: '/contact', component: Contact }
]
const router = new VueRouter({
routes,
mode: 'history'
})
其 webpack.config.js 中的插件配置与本示例几乎一致(同样的 routes: ['/', '/about', '/contact'] 与 renderAfterDocumentEvent: 'render-event'),构建后三个路由会分别生成真实的静态页面,可在浏览器分别访问 http://localhost:8000/、http://localhost:8000/about/、http://localhost:8000/contact/。
扩展方式:当应用新增页面时,只需把新路由(如 /some/deep/nested/route)追加进 routes 数组即可。文档提示"If you're using a router or have more than one page to prerender, edit the routes array"正是这个意思。仓库内 examples/vanilla-simple/webpack.config.js 甚至演示了 ['/', '/about', '/some/deep/nested/route'] 这样的深层嵌套路由写法。
六、开发模式:npm run dev 不触发预渲染
文档给出的开发命令同样是:
npm install
npm run dev
查看 package.json,dev 脚本为:
"dev": "cross-env NODE_ENV=development webpack-dev-server --open --hot"
在 NODE_ENV=development 下,webpack.config.js 走的是 else 分支——只挂载 DefinePlugin 和 HtmlWebpackPlugin,不添加 PrerenderSPAPlugin。这是有意为之的设计:预渲染是生产构建的产物,开发阶段借助 webpack-dev-server 的热更新(--hot)与 historyApiFallback: true 即可获得即时反馈,完全不需要也无必要执行耗时的无头浏览器渲染。
七、插件工作原理:从 afterEmit 钩子到静态文件落盘
从源码层面看,插件对 webpack 的介入点是 apply 方法(见 es6/index.js 第 54 行起)。它通过 compiler.hooks.afterEmit.tapAsync 注册到编译输出的 after-emit 阶段——即在 webpack 完成打包输出之后执行。核心流程(afterEmit 函数,es6/index.js)是一条清晰的 Promise 链:
- 初始化:
new Prerenderer(this._options)并initialize(),内部会启动静态服务器与渲染器; - 渲染路由:
renderRoutes(this._options.routes || [])逐个访问并渲染routes中声明的路由; - 兼容旧配置:若配置了 v2 时代的
postProcessHtml,先做兼容处理; - 执行 postProcess:若配置了
postProcess,对每个渲染结果调用一次(Promise.all并行); - 校验返回值:检查每个结果是否仍为对象,若忘记
return context会抛出"[prerender-spa-plugin] Rendered routes are empty, did you forget to return the \context` object in postProcess?"` 这样的明确报错; - 按需压缩:若配置了
minify,用html-minifier的minify()压缩 HTML; - 计算输出路径:若
outputPath未显式设置,默认写为path.join(outputDir || staticDir, route, 'index.html'); - 落盘:用
compiler.outputFileSystem逐级创建目录并写入processedRoute.html.trim()。
值得注意的是第 7 步的输出路径规则:/about 路由最终会落在 dist/about/index.html。而 postProcess 中可改写 renderedRoute.route 与 renderedRoute.outputPath 来改变输出位置——例如处理形如 /dir/special.html 的路由时,把默认的 dist/dir/special.html/index.html 修正为 dist/dir/special.html。postProcess 收到的上下文对象字段为:
{
route: String, // 跟随重定向后的路由
originalRoute: String, // 重定向前传入的路由
html: String, // 该路由渲染出的 HTML
outputPath: String // 输出路径(不设置时在 postProcess 之后自动计算)
}
v2 兼容:如果沿用旧式参数调用 new PrerenderSPAPlugin(staticDir, routes, config),es6/index.js 会打印警告提示迁移到对象式配置,但功能仍可用。其中 captureAfterDocumentEvent、captureAfterElementExists、captureAfterTime 会被自动改名并搬运到 renderer 选项(见 es6/index.js)。
八、实战注意事项与常见坑
1. 只支持 HTML5 history 路由
根 README 的 "Caveats" 明确指出:prerender-spa-plugin 只适用于使用 HTML5 history API 路由的 SPA,index.html#/hash/route 形式的 hash 路由无法预渲染。这也是 examples/vue2-webpack-router/src/main.js 中必须写 mode: 'history' 的原因。
2. 依赖 <body> 的脚本要包在 DOMContentLoaded 里
如果代码依赖 <body> 已存在(几乎必然如此),请将其放入 DOMContentLoaded 回调中执行,否则插件捕获到的将是 JS 运行前的空页面内容。Vue 场景的写法:
const root = new Vue({ /* ... */ })
document.addEventListener('DOMContentLoaded', function () {
root.$mount('#app')
})
3. Vue 2 的 hydration 提示
若 Vue 预渲染遇到问题,可在根元素上添加 data-server-rendered="true" 属性,Vue 会把当前页面当作"已渲染应用"进行更新而不是整棵重渲染。该属性既可在 postProcess 中写入,也可在渲染前用 JS 修改 DOM(配合 renderAfterDocumentEvent)。
4. 内联样式与重复样式标签
如果依赖内联 CSS(即没有从 bundle 中提取 CSS),可能出现重复的 style 标签。根 README 建议用 extract-text-webpack-plugin 将 CSS 提取为独立文件,再通过 html-webpack-plugin 注入到模板,或作为外部 CSS 引用。
5. 客户端渲染库需能接管预渲染内容
渲染库至少要能够替换或 diff 服务端预渲染的内容:Vue 1 需在根组件使用 replace: false;Vue 2 需确保根组件 id 与预渲染元素的 id 一致(本例中即为 index.html 模板 index.html 里的 <div id="app">),否则会出现内容重复。
至此,从构建、配置、渲染时机到底层原理,你已经掌握了用 prerender-spa-plugin 为 Vue 2 + Webpack 项目生成预渲染静态页面的完整链路。仓库中还有 vanilla-simple、vue2-webpack-router、create-react-app 与 angular-cli-eject 等更多框架示例可供对照,其中 examples/vanilla-simple/src/main.js 还演示了通过 window['__PRERENDER_INJECTED'] 读取 inject 注入数据的用法,可以作为进一步探索的起点。