@vaultkit/vitepress-plugin-plausible 为 VitePress 注入隐私优先的 Plausible 统计脚本。与姊妹包 @vaultkit/vitepress-plugin-umami 同款机制：纯构建期函数，把配置转换成一条 head 内联脚本条目，塞进 head 数组即可。

内联 bootstrap 先做 Do Not Track 与 localhost/127.0.0.1 双重豁免，通过后才以 defer 挂载真实跟踪脚本。零运行时依赖，产物只是一段字符串。

• 为什么需要它
• 安装
• 快速上手
• 公开导出一览
• PlausibleOptions 逐项详解
  • domain（必填）
  • src
  • attrs
• 产物解析
• 设计机制：三要点
  • DNT 豁免
  • localhost 豁免
  • defer 加载
• Plausible 还是 Umami？
• 常见问题
• 相关链接

为什么需要它

Plausible 是无 Cookie、GDPR 合规、脚本不到 1KB 的开源统计服务，欧盟站长圈的事实标准。但官方接入片段同样有三个可以做得更好的地方：不尊重 DNT、dev/preview 的本地访问会污染线上数据、以及需要自己记得加 defer。本包把这三点连同「自托管地址切换」固化成一个函数——统计接入从「抄片段再改三处」变成「传两个参数」。

如果你还在 Umami 与 Plausible 之间犹豫，本文末尾有选型对比；两个包的 API 刻意保持同构，换服务商时配置迁移是分钟级的。

安装

pnpm add -D @vaultkit/vitepress-plugin-plausible

使用 @vaultkit/vitepress-theme-vault 主题则开箱即带：site 配置里 features.analytics 传 provider: 'plausible' 判别式对象即可（缺省不开启，统计是显式 opt-in）：

export default defineConfigWithTheme({
  extends: createVaultTheme({
    site: { /* ... */ },
    features: {
      analytics: {
        provider: 'plausible',
        domain: 'example.com',
      },
    },
  }),
})

主题按 provider 分派到本包或 umami 包，其余字段原样透传——AnalyticsConfig 类型就是两包选项加判别式的联合。

快速上手

裸 VitePress 场景，.vitepress/config.ts 的 head 注入：

.vitepress/config.ts

import { plausibleHead } from '@vaultkit/vitepress-plugin-plausible'
import { defineConfig } from 'vitepress'

export default defineConfig({
  head: [
    plausibleHead({
      domain: 'example.com',
    }),
  ],
})

最小配置只有一个 domain——脚本地址缺省指向官方云服务。部署上线后访问几次（本地预览被豁免，看不到数据），Plausible 后台实时面板即有记录。

公开导出一览

导出	形态	说明
plausibleHead	函数	(options: PlausibleOptions) => PlausibleHeadEntry，生成 head 条目
PlausibleOptions	类型	选项接口
PlausibleHeadEntry	类型	[string, Record<string, string>, string]——VitePress HeadConfig 的结构化子集，免除对 vitepress 的类型依赖

PlausibleOptions 逐项详解

domain（必填）

• 类型：string
• 语义：站点域名（不含协议，如 example.com），注入为脚本的 data-domain 属性。Plausible 以域名为站点主键，后台建站时填的域名必须与这里一致，否则事件会被丢弃。

src

• 类型：string，默认 'https://plausible.io/js/script.js'
• 语义：跟踪脚本地址。官方云服务用户不用管；自托管实例（Plausible CE）一行覆盖：

plausibleHead({
  domain: 'example.com',
  src: 'https://analytics.example.com/js/script.js',
})

这也是与 umami 包的一处刻意差异：Plausible 有明确的官方云端点，所以 src 带缺省值；Umami 以自托管为第一公民，src 必填。

attrs

• 类型：Record<string, string>，默认 undefined
• 语义：附加 <script> 属性透传，Plausible 的扩展配置全部经此注入。常用项：

plausibleHead({
  domain: 'example.com',
  attrs: {
    'data-api': '/api/event', // 上报端点走同域反代，绕过广告拦截器对第三方域的误杀
  },
})

Plausible 的扩展能力也常用「换脚本变体」表达（如 script.outbound-links.js 统计出站点击、script.hash.js 支持 hash 路由），这类直接改 src 文件名即可，无需 attrs。同名键会覆盖内置的 data-domain，一般不要这么做。

产物解析

plausibleHead(...) 返回 ['script', {}, bootstrap]，最终渲染进每页 HTML 的内联脚本（为可读性加了换行，实际是单行）：

<script>
  (function () {
    if ((navigator.doNotTrack || window.doNotTrack) === '1'
      || location.hostname === 'localhost'
      || location.hostname === '127.0.0.1')
      return
    var s = document.createElement('script')
    s.defer = true
    s.src = 'https://plausible.io/js/script.js'
    s.setAttribute('data-domain', 'example.com')
    document.head.appendChild(s)
  })()
</script>

豁免命中时页面上不存在任何跟踪脚本节点——不加载，而非「加载但不上报」。

设计机制：三要点

DNT 豁免

navigator.doNotTrack（旧浏览器为 window.doNotTrack）为 '1' 时直接返回。用户在浏览器层面表态过「不要跟踪」，隐私优先的选型应当把这个表态执行到底——即便 Plausible 本身不设 Cookie、不存个人数据。

localhost 豁免

location.hostname 为 localhost / 127.0.0.1 时直接返回。head 注入是构建期静态行为，dev / preview / 生产共用同一份配置；把豁免放在客户端运行时判断，同一份构建产物在任何环境都行为正确，不需要维护「开发配置不注入统计」的双份配置。

defer 加载

真实脚本节点以 defer 动态创建，HTML 解析完成后才执行，首屏关键渲染路径零阻塞。Plausible 官方脚本自带 SPA 路由跟踪，VitePress 客户端路由切换自动计为浏览，无需额外埋点。

Plausible 还是 Umami？

注入机制两包完全一致，差异全在服务侧：

维度	Plausible	Umami
托管服务	成熟付费云（EU 数据驻留）	Cloud 有免费档
自托管栈	Elixir + Postgres + ClickHouse，较重	Node + Postgres/MySQL，Docker 一键，轻
配置主键	domain（域名即站点）	websiteId（UUID，一实例多站点）
src 缺省	有（官方云）	无（必填，自托管优先）
扩展方式	换脚本变体 + data-api	data-* 属性族

一句话建议：愿意付费买省心、看重 EU 数据驻留选 Plausible；想零成本自托管、或要一个实例管一堆小站选 Umami。两者都无 Cookie、匿名聚合、脚本 KB 级，对博客场景数据维度足够且高度重叠——纠结服务商不如先上线，反正换包只是改一行 import。

常见问题

Q：部署后后台没数据？ 逐项排查：domain 与 Plausible 后台建站域名是否逐字一致；是否还在本地/预览域名访问（localhost 豁免）；浏览器是否开了 DNT 或广告拦截器（前者被豁免、后者可能拦掉 plausible.io 域）。

Q：广告拦截器把统计脚本拦了？ 自托管或反代是正解：src 换成自己域名下的脚本地址，配合 attrs['data-api'] 把上报端点也收进同域。

Q：从官方云迁到自托管（Plausible CE）要改什么？ 只改 src 指向自托管实例的 /js/script.js；domain 保持不变（自托管后台按同域名重建站点）。

Q：想统计出站链接点击？src 换成 https://plausible.io/js/script.outbound-links.js（或自托管对应路径）——Plausible 的功能开关就是脚本文件名。

相关链接

• npm：@vaultkit/vitepress-plugin-plausible
• Plausible 官网：https://plausible.io
• 姊妹包（Umami 同款机制）：umami：隐私优先的 Umami 统计接入
• 集成本包的主题：@vaultkit/vitepress-theme-vault