prerender-spa-plugin 实战:Vue 2 + Webpack 预渲染静态 HTML 页面指南

原创2026-10-14 12:06:021,703 阅读
文章标签:前端

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 链:

  1. 初始化:new Prerenderer(this._options) 并 initialize(),内部会启动静态服务器与渲染器;
  2. 渲染路由:renderRoutes(this._options.routes || []) 逐个访问并渲染 routes 中声明的路由;
  3. 兼容旧配置:若配置了 v2 时代的 postProcessHtml,先做兼容处理;
  4. 执行 postProcess:若配置了 postProcess,对每个渲染结果调用一次(Promise.all 并行);
  5. 校验返回值:检查每个结果是否仍为对象,若忘记 return context 会抛出 "[prerender-spa-plugin] Rendered routes are empty, did you forget to return the \context` object in postProcess?"` 这样的明确报错;
  6. 按需压缩:若配置了 minify,用 html-minifier 的 minify() 压缩 HTML;
  7. 计算输出路径:若 outputPath 未显式设置,默认写为 path.join(outputDir || staticDir, route, 'index.html');
  8. 落盘:用 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 注入数据的用法,可以作为进一步探索的起点。

登录后查看全文
prerender-spa-plugin