首页
/ 在 Next.js 中集成 Facebook Pixel：App Router 与 Pages Router 双实现完整指南

在 Next.js 中集成 Facebook Pixel：App Router 与 Pages Router 双实现完整指南

2026-09-06 19:00:33作者：何将鹤
next.js
The React Framework
项目地址：https://gitcode.com/GitHub_Trending/next/next.js

本指南基于本仓库 examples/with-facebook-pixel 示例，系统讲解如何在 Next.js 应用中接入 Facebook Pixel，实现页面浏览（PageView）追踪与转化事件上报。示例同时提供 App Router（Next.js 13+）与 Pages Router 两套完整实现：你将掌握通过 next/script 注入像素基础代码、在路由切换时上报 PageView、以及通过环境变量安全配置 Pixel ID 的完整实战方案。

示例概览：同一套追踪逻辑，两种路由实现

Facebook Pixel 的本质是一段加载 fbevents.js 并初始化 fbq 全局函数的脚本，之后所有事件都通过 window.fbq("track", EventName, options) 发送。在 Next.js 中集成它需要解决两个关键问题：

  1. 在哪注入初始化脚本：脚本属于第三方分析代码，需要与 React 渲染解耦；
  2. 如何感知客户端路由切换：SPA 场景下浏览器不会整页刷新，必须在每次路由变化后手动补发 PageView。

本示例目录同时包含两套实现（详见 examples/with-facebook-pixel）：

  • app/：App Router 实现，面向 Next.js 13+；
  • _pages/：Pages Router 实现。注意目录名为 _pages 而非 pages，是为了让两套代码共存于一个示例中而不被 Next.js 同时识别路由；若要在实际项目使用 Pages Router 方案，需将其重命名为 pages；
  • lib/fpixel.js：被两套实现共享的像素封装模块。

两套方案共享同一逻辑核心，仅在"注入位置"与"路由监听方式"上有所区别，下面逐步展开。

准备工作：通过环境变量配置 Pixel ID

Pixel ID 属于公开信息（会随页面源码暴露），因此使用 NEXT_PUBLIC_ 前缀的环境变量，使其在构建时内联进客户端代码。

复制环境变量模板：

cp .env.local.example .env.local

.env.local.example 的内容只有一个键（见 .env.local.example）：

NEXT_PUBLIC_FACEBOOK_PIXEL_ID=

将其值替换为你 Facebook 像素的真实 ID，.env.local 会被 Git 忽略（示例目录中已配置 .gitignore）。这里的关键设计是：所有源码都只引用 lib/fpixel.js 导出的常量，绝不硬编码像素 ID，便于在多个环境（开发/预发/生产）间切换，也不会把 ID 泄露进版本库。

共享封装：lib/fpixel.js

lib/fpixel.js 是追踪逻辑的唯一出口，导出三个成员：

export const FB_PIXEL_ID = process.env.NEXT_PUBLIC_FACEBOOK_PIXEL_ID;

export const pageview = () => {
  window.fbq("track", "PageView");
};

// https://developers.facebook.com/docs/facebook-pixel/advanced/
export const event = (name, options = {}) => {
  window.fbq("track", name, options);
};
  • FB_PIXEL_ID：从 process.env.NEXT_PUBLIC_FACEBOOK_PIXEL_ID 读取；
  • pageview()：上报标准 PageView 事件；
  • event(name, options)：上报自定义事件（如 Purchase），可携带货币、金额等参数，对应 Facebook 的 CAPI/标准事件规范。

这个模块被两套实现同时引用，保证事件 API 一致、改动单点化。

方式一：Pages Router 实现

Pages Router 方案基于两个约定文件：pages/_document.js 负责文档级注入，pages/_app.js 负责全局逻辑与路由监听。

1. 在 _document 中注入无脚本兜底

自定义 _document 在服务端渲染 HTML 骨架时，向 <head> 写入 <noscript> 兜底图片：

import { Html, Head, Main, NextScript } from "next/document";
import { FB_PIXEL_ID } from "../lib/fpixel";

export default function Document() {
  return (
    <Html>
      <Head>
        <noscript>
          <img
            height="1"
            width="1"
            style={{ display: "none" }}
            src={`https://www.facebook.com/tr?id=${FB_PIXEL_ID}&ev=PageView&noscript=1`}
          />
        </noscript>
      </Head>
      <body>
        <Main />
        <NextScript />
      </body>
    </Html>
  );
}

这是 Facebook 官方要求的兜底机制：当用户浏览器禁用 JavaScript 时，向 facebook.com/tr 发起一次带 ev=PageView 的 1×1 像素请求，仍能记录一次访问。FB_PIXEL_ID 直接由服务端渲染时拼接，字符串安全无需担心转义问题。

2. 在 _app 中注入基础代码并监听路由

_app 是整个 Pages Router 方案的核心：

import { useEffect } from "react";
import Script from "next/script";
import { useRouter } from "next/router";
import * as fbq from "../lib/fpixel";

function MyApp({ Component, pageProps }) {
  const router = useRouter();

  useEffect(() => {
    // 首次进入页面只触发一次 PageView（保证像素拿到真实信息）
    fbq.pageview();

    const handleRouteChange = () => {
      fbq.pageview();
    };

    router.events.on("routeChangeComplete", handleRouteChange);
    return () => {
      router.events.off("routeChangeComplete", handleRouteChange);
    };
  }, [router.events]);
  ...
}

同时通过 next/script 的内联脚本注入 Facebook 官方基础代码（base code），完成 fbq 的初始化：

<Script
  id="fb-pixel"
  strategy="afterInteractive"
  dangerouslySetInnerHTML={{
    __html: `
      !function(f,b,e,v,n,t,s)
      {if(f.fbq)return;n=f.fbq=function(){n.callMethod?
      n.callMethod.apply(n,arguments):n.queue.push(arguments)};
      if(!f._fbq)f._fbq=n;n.push=n;n.loaded=!0;n.version='2.0';
      n.queue=[];t=b.createElement(e);t.async=!0;
      t.src=v;s=b.getElementsByTagName(e)[0];
      s.parentNode.insertBefore(t,s)}(window, document,'script',
      'https://connect.facebook.net/en_US/fbevents.js');
      fbq('init', ${fbq.FB_PIXEL_ID});
    `,
  }}
/>
<Component {...pageProps} />

两点值得深入理解：

  • 为什么用 next/script 而非普通 <script>：strategy="afterInteractive" 会让浏览器在页面成为 interactive 之后才执行该脚本，避免阻塞首屏渲染，同时又能保证在 React 水合完成前像素尽早就绪。这是该示例相对于"直接把脚本写进 _document"的更优实践。
  • 为什么监听 routeChangeComplete：Next.js 客户端路由切换是 SPA 式导航，页面不会刷新，因此每个路由事件都不会自动触发像素。useEffect 先补发一次当前页面的 PageView，随后注册 routeChangeComplete 处理器——该事件在所有路由变化完成后触发，此时再上报 PageView 能保证对应的 DOM 已经更新完毕。清理函数中 off 掉监听，避免重复挂载造成事件泄漏。注释特意强调"首次 PageView 对像素拿真实信息至关重要"，因为若只监听路由事件，首屏访问就会被漏掉。

3. 页面级转化事件上报

首页 _pages/index.js 演示了如何触发转化事件：

const handleClick = () => {
  fbq.event("Purchase", { currency: "USD", value: 10 });
};

点击"Buy $10"按钮即上报一次价值 10 美元的 Purchase 转化。而 _pages/navigation.js 则用于演示纯客户端导航：导航到新页面会触发 PageView 上报，但不会重新初始化像素。

方式二：App Router 实现（Next.js 13+）

App Router 没有 _app/_document 全局约定，示例的解法是把像素封装成一个客户端组件，挂在根布局中。目录中 app/readme.txt 明确标注这是 Next 13+ 的实现方式。

1. 封装 FacebookPixel 客户端组件

app/components/FacebookPixel.js 是 App Router 方案的核心：

"use client";

import { usePathname } from "next/navigation";
import Script from "next/script";
import { useEffect, useState } from "react";
import * as pixel from "../../lib/fpixel";

const FacebookPixel = () => {
  const [loaded, setLoaded] = useState(false);
  const pathname = usePathname();

  useEffect(() => {
    if (!loaded) return;
    pixel.pageview();
  }, [pathname, loaded]);

  return (
    <div>
      <Script
        id="fb-pixel"
        src="/scripts/pixel.js"
        strategy="afterInteractive"
        onLoad={() => setLoaded(true)}
        data-pixel-id={pixel.FB_PIXEL_ID}
      />
    </div>
  );
};

export default FacebookPixel;

该组件与 Pages Router 方案相比有三个明显差异：

  • "use client" 指令：App Router 默认服务器组件，而像素依赖 window/useEffect，必须显式标记为客户端组件；
  • 用 usePathname() 替代 router.events：App Router 中取消了 routeChangeComplete 事件，改为由 usePathname 提供的路径字符串作为 effect 依赖。每次路由变化导致 pathname 更新，effect 重新执行并上报一次 PageView；
  • 加载状态门控：onLoad 回调在 pixel.js 真正执行完、fbq 初始化就绪后把 loaded 置为 true，effect 中 if (!loaded) return 保证初始化完成后才补发首屏 PageView——否则会在 fbq('init') 执行前就调用 window.fbq，导致事件丢失或报错。pathname 变化与 loaded 翻转共同触发上报，逻辑上等价于 Pages Router 中"首屏一次 + 路由切换各一次"。

2. 通过静态脚本与 data-* 属性注入基础代码

App Router 方案没有沿用内联 dangerouslySetInnerHTML 注入 Facebook 官方基础代码，而是把同样的代码段抽成静态文件 public/scripts/pixel.js，通过外部 <script> 加载：

const PIXEL_ID = document.currentScript.getAttribute("data-pixel-id");

function initializeFacebookPixel(f, b, e, v, n, t, s) { ... } // Facebook 官方基础代码

initializeFacebookPixel(window, document, "script", "https://connect.facebook.net/en_US/fbevents.js");
window.fbq("init", PIXEL_ID);

它利用 document.currentScript.getAttribute("data-pixel-id") 读取组件上通过 data-pixel-id={pixel.FB_PIXEL_ID} 传入的像素 ID——脚本本身不含任何业务配置，ID 由 React 组件在渲染时注入，从而既保留了静态文件的缓存友好性，又避免把 ID 硬编码进 public 目录。public 下的文件会被原样托管到站点根路径，因此 src="/scripts/pixel.js" 可被直接访问。

3. 在根布局中挂载

app/layout.js 中，根布局以服务器组件形式渲染，像素组件作为独立的客户端子树挂载在 <body> 尾部：

import { FacebookPixel } from "./components";

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        {children}
        <FacebookPixel />
      </body>
    </html>
  );
}

由于根布局在 App Router 中属于共享 UI，任何页面切换都不会卸载重挂该布局，FacebookPixel 组件得以跨页面保持存活——这正是 usePathname 方案能持续监听路由变化的前提。app/page.js 与 app/about/page.js 提供两个页面用于实际验证跨页面跳转时的 PageView 上报行为。app/components/index.js 只是组件的桶文件（barrel export）。

如何创建与运行本示例

通过 create-next-app（源码位于 packages/create-next-app）的 --example 参数拉取该示例，三种包管理器任选其一：

npx create-next-app --example with-facebook-pixel with-facebook-pixel-app

yarn create next-app --example with-facebook-pixel with-facebook-pixel-app

pnpm create next-app --example with-facebook-pixel with-facebook-pixel-app

随后配置环境变量并启动：

cp .env.local.example .env.local
# 将 NEXT_PUBLIC_FACEBOOK_PIXEL_ID 填为你的真实 Pixel ID
npm run dev

项目的 package.json 依赖极简，仅 next、react、react-dom，未引入任何第三方统计 SDK，并声明了标准的 dev/build/start 脚本。本地验证时可通过浏览器开发者工具确认：首次加载触发一次 PageView、fbq('init') 携带正确 ID；通过 Link 在页面间跳转时，每次路径变化追加一次 PageView 且不重复初始化像素；点击"Buy $10"按钮后出现携带 {currency: "USD", value: 10} 的 Purchase 事件。

两套实现的关键差异速查

环节 Pages Router（_pages） App Router（app）
基础代码注入 next/script 内联 dangerouslySetInnerHTML（见 _pages/_app.js） 外部静态脚本 pixel.js + data-pixel-id（见 public/scripts/pixel.js）
首屏 PageView useEffect 挂载时直接补发 依赖 loaded 状态，待 pixel.js 加载完成后补发
路由切换监听 router.events 的 routeChangeComplete usePathname() 作为 effect 依赖
注入位置 _app.js 全局组件 根布局挂载的客户端组件
无 JS 兜底 _document.js 中 <noscript> 图片（见 _pages/_document.js） 与 Pages Router 共用同一 _document 机制
事件封装 共用 lib/fpixel.js 的 pageview/event 完全一致

无论采用哪种路由模型，代码都遵循同样的设计原则：像素初始化脚本与业务组件解耦、Pixel ID 通过 NEXT_PUBLIC_ 环境变量注入、所有追踪调用收敛到 lib/fpixel.js 单一模块。这套结构可直接迁移到真实项目中，作为接入 Meta 广告转化追踪、再营销人群（Custom Audience）等能力的基础设施。

next.js
The React Framework
项目地址：https://gitcode.com/GitHub_Trending/next/next.js
登录后查看全文

相关内容推荐

1 Next.js Pages Router 到 App Router 迁移实战：从文件结构、Metadata 到可验证的完整迁移路径2 Next.js Pages Router 集成 Socket.IO 实战：基于自定义 Server 的实时通信示例3 Next.js 文档写作规范详解：Frontmatter 模式、代码块格式与 MDX 组件标准4 Excalidraw 接入 Next.js：with-nextjs 示例中 App Router 与 Pages Router 的完整集成方案5 Lingui.js 在 Next.js 中的国际化实践指南6 Next.js 从 Pages Router 完整迁移到 App Router：以博客应用的迁移任务为实战范本7 解决Ant Design X在Next.js Pages Router中的兼容性问题8 Material UI × Next.js 集成实战：App Router 与 Pages Router 的服务端样式渲染完整方案9 Next.js 文档同步实战：基于 update-docs 技能的代码变更到 docs/ 的完整维护工作流10 Facebook/Relay 在 Next.js 应用路由中的支持情况解析
热门项目推荐
相关项目推荐

热门内容推荐

1 编程实践项目探索指南：从零构建技术能力体系2 技术解构式学习：从0到1构建你的编程知识体系3 构建自己的技术世界：build-your-own-x项目的实践探索指南4 解锁编程技能的实践之旅：从零构建你的技术世界5 技术实践探索：从零开始构建核心系统的实践指南6 亲手锻造技术引擎：从0到1构建核心系统的实践指南

最新内容推荐

LobeHub deep-review 对抗式验证子代理：逐条证伪代码审查发现的设计与实现AutoGen Python 文档构建实战：Sphinx + MyST + Poe 的本地构建与开发管线Go 项目目录布局详解：project-layout 标准目录结构的设计原则与实操指南深入 goccy/go-yaml：lazydocker 的 YAML 编解码、Anchor/Alias 与 YAMLPath 实现解析CrewAI FirecrawlScrapeWebsiteTool 完全指南：让 Agent 把任意网站抓成干净 MarkdownSupabase pm-the-docs：文档创作 Frame/Shape 阶段的决策支持技能——受众、产品阶段与跨仓库范围判定Headroom 贡献指南全解：从 PR 工作流、Real behavior proof 到本地开发环境与架构原则Crawl4AI v0.7.4 版本深度解析：LLM 智能表格抽取（LLMTableExtraction）与并发、稳定性改进free-programming-books 芬兰语免费编程书目全解：fi 列表中 C 到 Ruby 的完整学习资源地图three.js TSL 中 BasicLightMapNode 解析：无光照材质如何正确处理 Light Map

项目优选

收起
kernelkernel
deepin linux kernel
C
33
18
pytorchpytorch
作为 Ascend for PyTorch 社区的核心组件，TorchNPU 是昇腾专为 PyTorch 打造的深度学习适配插件，使 PyTorch 框架能够直接调用昇腾 NPU，为开发者提供昇腾 AI 处理器的超强算力。
Python
855
1.34 K
ops-transformerops-transformer
本项目是CANN提供的transformer类大模型算子库，实现网络在NPU上加速计算。
C++
1.13 K
2.73 K
kernelkernel
openEuler内核是openEuler操作系统的核心，既是系统性能与稳定性的基石，也是连接处理器、设备与服务的桥梁。
C
528
589
ops-nnops-nn
本项目是CANN提供的神经网络类计算算子库，实现网络在NPU上加速计算。
C++
908
1.83 K
jiuwenswarmjiuwenswarm
JiuwenSwarm 是一款基于openJiuwen开发的智能AI Agent，它能够将大语言模型的强大能力，通过你日常使用的各类通讯应用，直接延伸至你的指尖。
Python
3.56 K
1.01 K
cann-learning-hubcann-learning-hub
CANN 学习中心仓，支持在线互动运行、边学边练，提供教程、示例与优化方案，一站式助力昇腾开发者快速上手。
Jupyter Notebook
997
511
ops-mathops-math
本项目是CANN提供的数学类基础计算算子库，实现网络在NPU上加速计算。
C++
1.34 K
1.45 K
docsdocs
暂无描述
Markdown
895
5.79 K
openGauss-serveropenGauss-server
openGauss kernel ~ openGauss is an open source relational database management system
C++
213
313