---
title: Plausible Analytics 集成
description: 为文档站点添加 Plausible Analytics，以隐私优先、轻量的方式获取流量数据，无需 Cookie 或跟踪脚本。
---

> **For AI agents:** the complete documentation index is at [llms.txt](/docs/llms.txt). Append `.md` to any page URL for its markdown version.

为文档站点添加 Plausible Analytics，在无需 Cookie 或跟踪脚本跟随用户浏览的情况下获取流量数据。

<Info>
Plausible 是开源工具，体积小于 1 KB，并且在大多数司法管辖区无需显示 Cookie 同意横幅。如果你需要简单且符合 GDPR 的分析功能，它是一个不错的选择。
</Info>

如果确实需要征得同意（或同时运行 GA、GTM 或 Crisp），请参阅 [Cookie 同意管理](/cn/integrations/cookie-consent)。

添加 Plausible 有两种方式。请选择与设置相匹配的方式：

| 设置 | 适用场景 | 字段 |
|-------|----------|-------|
| **标准** | 使用 Plausible 免费套餐，或使用付费套餐但不需要代理 | `domain` |
| **代理脚本** | 使用付费套餐并希望绕过广告拦截器 | `scriptUrl` |

## 标准设置 (domain)

这是大多数用户的默认设置。在 Plausible 中注册站点并传入域名。

<Steps>

### 注册 Plausible

在 [Plausible Analytics](https://plausible.io/) 创建账户，并添加文档站点域名（例如 `docs.example.com`）。

### 将域名添加到 docs.json

```json docs.json
{
  "name": "My Docs",
  "integrations": {
    "plausible": {
      "domain": "docs.example.com"
    }
  }
}
```

使用你注册的确切域名：`docs.example.com`，而不是 `www.docs.example.com`。

</Steps>

### 自托管服务器

如果你运行的是 [Community Edition](https://github.com/plausible/community-edition)，请添加 `server` 字段，使脚本和事件 API 指向你的实例：

```json docs.json
{
  "name": "My Docs",
  "integrations": {
    "plausible": {
      "domain": "docs.example.com",
      "server": "https://analytics.example.com"
    }
  }
}
```

`server` 只能与 `domain` 搭配使用。代理脚本会自行处理路由。

## 代理脚本设置 (scriptUrl)

Plausible 的付费套餐提供带有唯一文件名的代理脚本（例如 `pa-XXXXX.js`）。由于脚本 URL 不匹配常见的过滤列表，这些脚本可以绕过大多数广告拦截器。

<Steps>

### 获取代理脚本 URL

在 Plausible 站点设置中找到代理脚本部分，然后复制完整 URL。其格式类似于 `https://plausible.io/js/pa-XXXXX.js`。

### 将脚本 URL 添加到 docs.json

```json docs.json
{
  "name": "My Docs",
  "integrations": {
    "plausible": {
      "scriptUrl": "https://plausible.io/js/pa-XXXXX.js"
    }
  }
}
```

无需 `domain` 或 `server` 字段。站点身份已嵌入脚本 ID，Plausible 的 CDN 会在内部处理路由。

</Steps>

## 验证安装

添加集成后：

1. 触发文档重新构建
2. 访问在线文档站点
3. 检查 Plausible 仪表板。你的访问应在几秒内显示。
4. 或打开 DevTools，转到 Network 标签页，然后查找对 `plausible.io/js/script.js`（标准脚本）或你的 `pa-XXXXX.js` 脚本（代理脚本）的请求

<Note>
Plausible 会实时显示数据，不像 Google Analytics 那样需要等待。
</Note>

## 配置参考

| 字段 | 类型 | 必填 | 描述 |
|-------|------|----------|-------------|
| `domain` | `string` | `domain` 或 `scriptUrl` 二选一 | 在 Plausible 中注册的站点域名。用作脚本标签上的 `data-domain` 属性。 |
| `scriptUrl` | `string` | `domain` 或 `scriptUrl` 二选一 | Plausible 付费代理脚本的完整 URL（`pa-XXXXX.js`）。站点身份已写入脚本，因此无需 domain 字段。 |
| `server` | `string` | 否 | 自托管 Plausible 服务器的 URL。仅与 `domain` 搭配使用，不能与 `scriptUrl` 搭配。 |

## 故障排除

<Accordion title="在 Plausible 中看不到任何数据">
  十有八九是域名的问题。它必须与你在 Plausible 中注册的域名完全匹配（即 `docs.example.com`，而不是 `www.docs.example.com`）。

  如果域名看起来正确：

  1. 重新构建文档。配置更改只有在新的构建完成后才会生效。
  2. 检查广告拦截器。某些浏览器扩展会拦截包括 Plausible 在内的分析脚本。如果确定是此原因，请切换到[代理脚本设置](#代理脚本设置-scripturl)。
  3. 检查页面源代码中是否有带 `data-domain` 的 `<script>` 标签（标准脚本），或是否有你的 `pa-XXXXX.js` 文件名（代理脚本）。如果没有，说明配置未生效。
</Accordion>

<Accordion title="使用自定义域名或子目录">
  注册用户实际访问的域名。如果文档位于 `docs.example.com`，请将其用作 `domain`，而不是根域名。
</Accordion>

<Accordion title="脚本被广告拦截器阻止">
  切换到[代理脚本设置](#代理脚本设置-scripturl)。唯一的文件名可以绕过大多数广告拦截器的过滤列表。自行托管也能达到相同效果，因为脚本会从你自己的域名加载。
</Accordion>

<Accordion title="何时使用 domain 或 scriptUrl">
  如果使用免费套餐，或不在意广告拦截器，请使用 `domain`。如果使用付费套餐并希望获得最大程度的跟踪覆盖范围，请使用 `scriptUrl`。不要同时设置两者，请选择其一。
</Accordion>

## 相关文章

<Columns cols={2}>
  <Card title="Google Analytics" icon="chart-simple" href="/cn/integrations/google-analytics">
    将 GA4 跟踪添加到文档
  </Card>
  <Card title="项目分析" icon="chart-line" href="/cn/setup/project-analytics">
    查看 Jamdesk 内置的分析功能
  </Card>
</Columns>