在 Next.js App Router 中集成 Plausible 隐私友好分析：with-plausible 示例全解析

2026-09-07 09:21:41作者：瞿蔚英Wynne

导读

本文围绕 examples/with-plausible 官方示例，系统讲解如何在 Next.js 应用中集成轻量、隐私友好的网站分析工具 Plausible，实现页面访问自动追踪与自定义事件上报。读完本文你将掌握 next-plausible 的完整接入流程，能直接在 App Router 的根布局中注入分析脚本，并在任意客户端组件中上报业务自定义事件。

一、示例概览：仓库结构与核心依赖

examples/with-plausible 是一个基于 Next.js App Router 的最小示例，目录结构如下：

examples/with-plausible/
├── app/
│   ├── layout.tsx        # 根布局：注入 PlausibleProvider
│   ├── page.tsx          # 首页
│   ├── about/page.tsx    # 关于页
│   └── contact/page.tsx  # 联系页：演示自定义事件上报
├── _components/
│   └── Header.tsx        # 三页面的共享导航
├── package.json
├── tsconfig.json
└── README.md

示例通过 next-plausible 这一第三方包与 Plausible 对接。查看 package.json，可以看到唯一的分析相关依赖是 "next-plausible": "^3.12.4"，其余为 Next.js、React 及 TypeScript 基础依赖，且示例遵循 @/* 路径别名（配置在 tsconfig.json 中 "@/*": ["./*"]），因此组件导入写作 @/_components/Header。

二、快速启动：三种包管理器一行命令

示例自带独立仓库式的工程文件，可以直接用 create-next-app 拉取。README 中给出的命令支持 npm、Yarn 与 pnpm 三种包管理器，任选其一：

npx create-next-app --example with-plausible with-plausible-app

yarn create next-app --example with-plausible with-plausible-app

pnpm create next-app --example with-plausible with-plausible-app

create-next-app 会把该示例完整复制到本地目录 with-plausible-app 并自动安装依赖。随后在项目目录内执行 npm run dev（即 next dev）即可在开发环境运行，next build / next start 分别对应生产构建与启动——这三个脚本同样定义在示例的 package.json 中。

提示：示例拉取自当前仓库的 examples/ 目录，若希望对照源代码研读，可直接查看 examples/with-plausible 内的全部文件。

三、在根布局中注入分析脚本：PlausibleProvider

Plausible 的接入点位于 App Router 的根布局（Root Layout）。示例在 app/layout.tsx 的 <head> 中挂载了 <PlausibleProvider />：

import PlausibleProvider from "next-plausible";
import Header from "@/_components/Header";

export const metadata = {
  title: "Next.js",
  description: "Generated by Next.js",
};

export default function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  return (
    <html lang="en">
      <head>
        <PlausibleProvider
          domain={process.env.NEXT_PUBLIC_DOMAIN}
          trackLocalhost
        />
      </head>
      <body>
        <Header />
        {children}
      </body>
    </html>
  );
}

3.1 关键配置解析

配置项	示例取值	作用说明
`domain`	`process.env.NEXT_PUBLIC_DOMAIN`	Plausible 后台中注册的站点域名，用于匹配数据归属。示例将其交给环境变量，保证同一套代码可部署到多环境
`trackLocalhost`	布尔（开启）	允许本地开发时也上报数据，便于在 `next dev` 下联调验证埋点是否生效

PlausibleProvider 位于根布局的 <head> 内，它会向页面注入 Plausible 的追踪脚本（默认按需加载）。由于它包裹着整棵页面树，因此所有页面的访问都会被自动记录，无需在每个页面重复配置。

值得注意的是 domain 取自 process.env.NEXT_PUBLIC_DOMAIN。这里的 NEXT_PUBLIC_ 前缀意味着该变量会暴露到浏览器端，因此必须在构建时提供（例如写入根目录的 .env.local，或在 Vercel 等平台的项目环境变量中配置）。示例未附带 .env 文件，实际使用时需自行创建：

NEXT_PUBLIC_DOMAIN=your-site.example.com

四、用 usePlausible 上报自定义事件

页面浏览之外的业务动作（如表单提交、按钮点击、付费转化）需要通过 自定义事件（custom events） 追踪。示例的 app/contact/page.tsx 演示了完整链路：这是一个标有 "use client" 的客户端组件，内部通过 next-plausible 导出的 usePlausible() Hook 拿到上报函数，在表单提交时发送事件：

"use client";

import { FormEvent, useState } from "react";
import { usePlausible } from "next-plausible";

export default function Contact() {
  const [message, setMessage] = useState("");
  const plausible = usePlausible();

  const handleSubmit = (e: FormEvent<HTMLFormElement>) => {
    e.preventDefault();

    plausible("customEventName", {
      props: {
        message,
      },
    });

    // your own submit logic
    setMessage("");
  };

  return (
    <div>
      <h1>This is the Contact page</h1>
      <form onSubmit={handleSubmit}>
        <label>
          <span>Message:</span>
          <textarea name="message" />
        </label>
        <button type="submit">submit</button>
      </form>
    </div>
  );
}

4.1 上报接口的使用要点

事件名称自定义：示例中的 "customEventName" 是占位符，实际项目中应替换为可读的事件名（如 "FormSubmitted"），该名称需与 Plausible 后台的 Goal（目标）配置一致，数据才会被统计。
携带业务属性：第二个参数 props 可携带任意结构化字段，示例把表单输入框中的 message 作为属性一并上报，便于在 Plausible 后台按维度拆分分析。
必须位于客户端：usePlausible 依赖浏览器运行时，因此所在组件需以 "use client" 声明为客户端组件，这与 Next.js App Router 的组件模型一致。
不影响业务逻辑：上报是旁路操作，示例中上报后仍继续执行“自己的提交逻辑”（源码注释 // your own submit logic），随后清空 message 状态，两者互不干扰。

4.2 多页面共享导航：Header 组件

为了让示例具备真实的“页面切换”场景，app/_components/Header.tsx 使用 next/link 的 Link 提供了 Home、About、Contact 三个页面的导航菜单：

import Link from "next/link";

export default function Header() {
  return (
    <header>
      <nav>
        <ul>
          <li>
            <Link href="/">Home</Link>
          </li>
          <li>
            <Link href="/about">About</Link>
          </li>
          <li>
            <Link href="/contact">Contact</Link>
          </li>
        </ul>
      </nav>
    </header>
  );
}

该组件在根布局中渲染，因此三个页面共享同一个导航。首页 app/page.tsx 与 app/about/page.tsx 均为最简单的静态组件，分别输出 This is the Home page 与 This is the About page，用于验证页面浏览追踪在路由切换（含客户端导航）时是否正常记录。

五、运行与验证建议

按上述流程启动后，建议按以下顺序验证：

启动开发服务器：在项目根目录执行 npm run dev，浏览器访问 http://localhost:3000。由于根布局开启了 trackLocalhost，本地访问也会产生上报。
浏览页面：依次点击 Home → About → Contact，观察每个页面访问是否被 Plausible 记录。
触发自定义事件：在 Contact 页面填写 Message 并点击 submit，此时会触发 customEventName 事件（携带 message 属性），可在 Plausible 后台的 Goals / Events 视图中核对。
多页共享验证：确认导航在各页面间切换正常，且无需在每个页面单独配置分析脚本——这正体现了根布局 + PlausibleProvider 的“一处注入、全站生效”优势。

需要强调的适用前提：NEXT_PUBLIC_DOMAIN 对应的域名必须已在你的 Plausible 账户中完成站点添加，否则上报数据不会归属到任何站点；同时 customEventName 等自定义事件名也应在 Plausible 后台事先配置为对应 Goal，方能形成可读的统计报表。

六、小结

通过 examples/with-plausible 可以看到，在 Next.js App Router 中接入 Plausible 只需三步：在 package.json 添加 next-plausible 依赖；在 app/layout.tsx 的 <head> 中通过 PlausibleProvider 注入站点域并开启 trackLocalhost；在需要追踪动作的客户端组件中调用 usePlausible() 上报带属性的自定义事件。该示例同时覆盖了“页面级流量自动统计”与“业务级事件主动上报”两种核心场景，可作为你在真实项目中接入 Plausible 或同类隐私友好分析服务的直接参考模板。

next.js

The React Framework

项目地址：https://gitcode.com/GitHub_Trending/next/next.js

登录后查看全文