VuePress 2配置vue-matomo遇window未定义错误的解决方法

问题原因 #

VuePress 2采用服务端渲染（SSR）模式构建，服务端环境不存在浏览器的window对象，而vue-matomo插件在初始化阶段直接访问了window，导致构建时抛出错误。你之前添加的ESLint配置只是告诉语法检查工具window是全局变量，无法解决运行时的环境差异问题。

解决方案 #

通过仅在客户端环境初始化vue-matomo来避免服务端执行访问window的代码，具体修改client.ts如下：

import { defineClientConfig } from '@vuepress/client'

export default defineClientConfig({
  async enhance({ app, router, siteData }) {
    // 仅在浏览器客户端环境加载并初始化插件
    if (process.client) {
      const { VueMatomo } = await import('vue-matomo')
      app.use(VueMatomo, {
        host: 'https://matomo.example.com',
        siteId: 5,
        router: router,
      })
    }
  },
  setup() {},
  rootComponents: [],
})

原理说明 #

• process.client是VuePress提供的环境变量，在客户端构建时会被解析为true，服务端构建时为false，以此确保插件初始化代码只在浏览器中执行。
• 使用async/await动态导入vue-matomo，避免服务端打包时加载该插件的代码，从根源上杜绝服务端访问window的可能。

验证 #

修改后重新执行npm run docs:build，即可正常完成构建，同时客户端会正常加载Matomo统计功能。

内容的提问来源于stack exchange，提问作者msampaio