Gatsby 接入 Google Analytics 完整指南gatsby-plugin-google-analytics 的配置、事件追踪与 Web Vitals 上报【免费下载链接】gatsbyReact-based framework with performance, scalability, and security built in.项目地址: https://gitcode.com/gh_mirrors/ga/gatsby本指南围绕 packages/gatsby-plugin-google-analytics/README.md 展开系统讲解如何在 Gatsby 站点中集成 Google Analytics从安装、gatsby-config.js选项配置到OutboundLink外链追踪、trackCustomEvent自定义事件上报再到 Core Web Vitals 真实用户指标采集与常见故障排查。读完本文你将掌握该插件全部配置项的语义与默认值并能结合源码理解其在 SSR 与浏览器端的完整工作链路。插件概览与弃用提示gatsby-plugin-google-analytics是一个在构建期为站点注入 Google Analytics 追踪脚本的官方插件底层依赖 Google 的analytics.js。它通过 Gatsby 的 SSR APIonRenderBody在 HTML 中输出内联追踪脚本通过浏览器 APIonRouteUpdate在路由切换时自动上报 pageview并额外提供了外链点击追踪组件与自定义事件函数开箱即用。需要特别注意的是官方已明确标注该插件为弃用Deprecated状态Google 官方推荐用户将analytics.js升级为gtag.js。仓库中提供了对应的替代插件 packages/gatsby-plugin-google-gtag/README.md新项目建议直接使用gatsby-plugin-google-gtag。若你正在维护存量站点或必须使用analytics.js生态本文内容依然完全适用。安装npm install gatsby-plugin-google-analytics从 package.json 可以看到该插件的运行时依赖仅有三个babel/runtime、minimatch用于将exclude的 glob 表达式编译为正则和web-vitals用于采集 Core Web Vitals 指标依赖面非常小。其 peerDependencies 要求 Gatsby^5.0.0、React^18.0.0 || ^19.0.0Node 版本要求18.0.0 26。基础接入在 gatsby-config.js 中启用插件完整配置示例在项目根目录的gatsby-config.js的plugins数组中注册插件并传入选项// In your gatsby-config.js module.exports { plugins: [ { resolve: gatsby-plugin-google-analytics, options: { // The property ID; the tracking code wont be generated without it trackingId: YOUR_GOOGLE_ANALYTICS_TRACKING_ID, // Defines where to place the tracking script - true in the head and false in the body head: false, // Setting this parameter is optional anonymize: true, // Setting this parameter is also optional respectDNT: true, // Avoids sending pageview hits from custom paths exclude: [/preview/**, /do-not-track/me/too/], // Delays sending pageview hits on route update (in milliseconds) pageTransitionDelay: 0, // Enables Google Optimize using your container Id optimizeId: YOUR_GOOGLE_OPTIMIZE_TRACKING_ID, // Enables Google Optimize Experiment ID experimentId: YOUR_GOOGLE_EXPERIMENT_ID, // Set Variation ID. 0 for original 1,2,3.... variationId: YOUR_GOOGLE_OPTIMIZE_VARIATION_ID, // Defers execution of google analytics script after page load defer: false, // Any additional optional fields sampleRate: 5, siteSpeedSampleRate: 10, cookieDomain: example.com, // defaults to false enableWebVitalsTracking: true, }, }, ], }注意trackingId是唯一必填项。在 gatsby-node.js 的插件选项校验pluginOptionsSchema中trackingId被标记为Joi.string().required()同时 gatsby-ssr.js 中也有if (process.env.NODE_ENV ! production || !pluginOptions.trackingId) return null的兜底判断——没有 trackingId 时整个追踪脚本都不会生成。开发环境自动禁用注意该插件在运行gatsby develop时是禁用的开发期间的页面行为不会被追踪。只有在gatsby build之后插件才启用可用gatsby serve对生产构建产物进行验证。这一行为在源码中有双重保证onRenderBodySSR与onRouteUpdate浏览器端都首先检查process.env.NODE_ENV ! production并直接返回。选项详解trackingId必填项填写你的 Google Analytics 媒体资源 ID形如UA-XXXXXXXX-X。它会被注入到内联脚本的ga(create, YOUR_TRACKING_ID, ...)调用中。head控制追踪脚本的注入位置设为true时脚本放在head中设为false时放在body末尾默认值为false见 gatsby-node.js 中的head: Joi.boolean().default(false)以及 gatsby-ssr.js 中const setComponents pluginOptions.head ? setHeadComponents : setPostBodyComponents的选择逻辑。anonymize部分国家如德国的隐私法规要求网站使用_anonymizeIP函数否则不允许使用 Google Analytics。开启该选项后插件会额外向页面注入两段代码function gaOptout(){document.cookiedisableStrtrue; expiresThu, 31 Dec 2099 23:59:59 UTC;path/,window[disableStr]!0}var gaPropertyUA-XXXXXXXX-X,disableStrga-disable-gaProperty;document.cookie.indexOf(disableStrtrue)-1(window[disableStr]!0); ... ga(set, anonymizeIp, 1);第一段定义了一个gaOptout()函数用于让访客通过 Cookie 声明“退出追踪”第二段在初始化后执行ga(set, anonymizeIp, true)对 IP 地址做匿名化处理。源码中这两段分别位于 gatsby-ssr.js内联函数与 gatsby-ssr.jsanonymizeIpset 命令。如果你希望访客能够主动关闭追踪可以在站点的法律声明/印记Imprint页面放置如下链接a hrefjavascript:gaOptout();Deactivate Google Analytics/arespectDNT开启后对于启用了“请勿追踪Do Not Track”的访客Google Analytics 脚本将完全不加载。虽然使用 Google Analytics 本身不一定构成法律意义上的追踪但面向注重隐私的用户这是一个值得开启的选项。源码在 gatsby-ssr.js 中通过navigator.doNotTrack/window.doNotTrack/navigator.msDoNotTrack三处检测来决定是否执行脚本加载分支。调试该功能时请务必先在浏览器中关闭 DNT 设置否则会误以为插件失效Chrome 中依次进入 设置 隐私和安全 更多然后关闭“随浏览流量发送‘请勿追踪’请求”。exclude传入一个 glob 表达式数组可包含通配符如/preview/**匹配到的路径不会发送 pageview 命中。插件在 SSR 阶段使用minimatch将每个 glob 编译为正则并拼装成window.excludeGAPaths[...]注入页面见 gatsby-ssr.js浏览器端在onRouteUpdate中会先检查当前pathname是否命中这些正则命中则直接跳过上报见 gatsby-browser.js。pageTransitionDelay如果你的站点在路由更新时使用了自定义过渡动画例如基于gatsby-plugin-transition-link的页面过渡可以设置该参数毫秒延迟发送 pageview直到新页面真正挂载完成。源码中会保证至少延迟 32msconst delay Math.max(32, pluginOptions.pageTransitionDelay || 0)见 gatsby-browser.js之所以有 32ms 的下限是为了等待 react-helmet 通过requestAnimationFrame完成title等头部标签的更新对应 GitHub issue #9139 的修复。测试用例 src/tests/gatsby-browser.js 同时验证了默认 32ms 与自定义值两条路径。optimizeId用于 Google OptimizeA/B 测试。传入 Optimize 容器 ID 后插件会执行ga(require, YOUR_OPTIMIZE_ID)让 analytics.js 加载对应的测试参数见 gatsby-ssr.js。experimentId与variationId两者配合用于配置服务端SERVER_SIDEGoogle Optimize 实验。experimentId是实验详情页右侧面板中显示的实验 IDvariationId是变体 ID0 表示原始版本。注入后插件会分别执行ga(set, expId, ...)与ga(set, expVar, ...)见 gatsby-ssr.js。defer控制 analytics.js 脚本的加载方式为false默认时使用a.async1异步加载为true时使用a.defer1将脚本执行推迟到页面解析完成后见 gatsby-ssr.js。测试 src/tests/gatsby-ssr.js 验证了两种模式下输出脚本的差异。enableWebVitalsTracking默认值为false见 gatsby-node.js。开启后插件会基于真实用户访问采集 Core Web Vitals 核心性能指标并作为事件上报到 Google Analytics帮助你用真实环境数据RUM评估用户体验。共上报三个指标Largest Contentful Paint (LCP)衡量加载性能。良好体验要求 LCP 在页面开始加载后的 2.5 秒内发生。First Input Delay (FID)衡量交互响应。良好体验要求页面的 FID 不超过 100 毫秒。Cumulative Layout Shift (CLS)衡量视觉稳定性。良好体验要求 CLS 不超过 1。从源码看该功能在浏览器端onInitialClientRender中触发gatsby-browser.js通过动态import(web-vitals/base)按需加载getLCP、getFID、getCLS三个方法其中 LCP 与 CLS 会先经过 3 秒防抖因为 LCP 可能多次触发、CLS 会持续变化FID 则在发生时立即发送gatsby-browser.js。发送时统一使用eventCategory: Web VitalseventLabel为当前页面加载的唯一 ID同一页面多次上报可按此分组聚合eventValue取整CLS 值会先乘 1000 以获得更高精度并且标记为nonInteraction: true、transport: beacon既不影响跳出率也能在页面卸载时可靠送达gatsby-browser.js。测试 src/tests/gatsby-browser.js 对三个指标的发送参数有完整断言。另外当enableWebVitalsTracking为 true 时插件还会向head注入一段web-vitals/polyfillgatsby-ssr.js为不支持 PerformanceObserver 的浏览器如部分 Chromium 系旧版本补齐 first-input 的降级监听能力。Optional Fields透传的 analytics.js 配置字段插件支持将 Google Analyticsanalytics.js的配置字段直接透传这些字段在 SSR 阶段会原样写入ga(create, ...)或ga(set, ...)调用。完整列表如下Create Only 字段随ga(create, ...)一起传入name: stringtracker 名称clientId: stringsampleRate: number采样率0-100如示例中的5表示只采集 5% 会话siteSpeedSampleRate: number站点速度采样率如10alwaysSendReferrer: booleanallowAnchor: booleancookieName: stringcookieFlags: stringcookieDomain: string不传时默认autocookieExpires: numberstoreGac: booleanlegacyCookieDomain: stringlegacyHistoryImport: booleanallowLinker: booleanstorage: stringGeneral 字段以ga(set, ...)命令写入allowAdFeatures: booleandataSource: stringqueueTime: numberforceSSL: booleantransport: string上述字段在源码中以knownOptions对象集中声明并带类型标注gatsby-ssr.jsCreate Only 字段会先按类型校验字符串/数字/布尔再合并进gaCreateOptions传入ga(create, ...)gatsby-ssr.jsGeneral 字段则在ga(create, ...)之后逐个拼接为ga(set, optionName, value)gatsby-ssr.js。一个值得注意的实现细节是只有类型匹配的字段才会被透传。测试 src/tests/gatsby-ssr.js 验证了传入allowAdFeatures: swag字符串而非布尔时该字段会被静默忽略避免把非法值写入追踪脚本。源码视角追踪脚本的完整生成流程理解了上述选项后可以把它们的最终去向串联起来。插件的 SSR 入口onRenderBodygatsby-ssr.js在每次构建时执行以下步骤非生产环境或无 trackingId 时直接返回不输出任何脚本无论是否注入追踪脚本都会在head中输出preconnect与dns-prefetch两个link指向https://www.google-analytics.com提前建立连接以优化脚本加载Lighthouse 建议做法根据head选项决定脚本输出位置setHeadComponents或setPostBodyComponents按需拼接window.excludeGAPaths、gaOptout()、respectDNT条件分支然后输出标准的 analytics.js 异步加载引导代码在ga可用时执行ga(create, trackingId, cookieDomain, gaCreateOptions)随后依次处理anonymizeIp、optimizeIdga(require, ...)、experimentId/variationIdga(set, ...)以及所有 General 字段。在浏览器端onRouteUpdategatsby-browser.js负责 SPA 路由切换时的自动上报拼装pathname search hash作为完整页面路径先ga(set, page, pagePath)再ga(send, pageview)并按照pageTransitionDelay下限 32ms延迟执行。OutboundLink组件一键追踪外链点击为了让外链点击的追踪足够简单插件导出了一个OutboundLink组件用法与a标签一致import React from react import { OutboundLink } from gatsby-plugin-google-analytics const Component () ( div OutboundLink hrefhttps://www.gatsbyjs.com/plugins/gatsby-plugin-google-analytics/ Visit the Google Analytics plugin page! /OutboundLink /div ) export default Component从源码实现src/index.js可以了解其内部行为组件本质是一个渲染为a的包装组件除事件字段外的所有 props如target、className、rel都会透传给原生a点击时先调用用户自定义的onClick如果传入只有当点击是普通左键单击e.button 0且未按住 Alt/Ctrl/Meta/Shift且未defaultPrevented、且未设置非_self的target时才通过transport: beacon发送事件并交给hitCallback跳转否则直接放行浏览器默认行为——这是为了避免新窗口打开或修饰键点击时被误拦截发送的事件默认参数为eventCategory: Outbound Link、eventAction: click、eventLabel: props.href你也可以通过eventCategory、eventAction、eventLabel、eventValue四个 props 覆盖默认值。对应的 TypeScript 类型在 index.d.ts 中定义组件测试见 src/tests/index.js。trackCustomEvent 函数上报自定义事件在业务逻辑或组件中上报自定义事件时可以引入trackCustomEventimport React from react import { trackCustomEvent } from gatsby-plugin-google-analytics const Component () ( div button onClick{e { // To stop the page reloading e.preventDefault() // Lets track that custom click trackCustomEvent({ // string - required - The object that was interacted with (e.g.video) category: Special Button, // string - required - Type of interaction (e.g. play) action: Click, // string - optional - Useful for categorizing events (e.g. Spring Campaign) label: Gatsby Plugin Example Campaign, // number - optional - Numeric value associated with the event. (e.g. A product ID) value: 43, }) //... Other logic here }} Tap that! /button /div ) export default Component全部字段category: string —必填被交互的对象类别如 videoaction: string —必填交互类型如 playlabel: string — 可选用于事件分类如 Spring Campaignvalue: integer — 可选与事件关联的数值如产品 IDnonInteraction: bool — 可选是否作为非交互事件默认falsetransport: string — 可选发送方式类型定义中限定为beacon | xhr | image见 index.d.tshitCallback: function — 可选命中成功后的回调callbackTimeout: number — 可选hitCallback的超时时间默认 1000ms函数内部src/index.js会先检查window.ga是否可用然后将参数组装为window.ga(send, event, {...})发送。hitCallback 的超时保护hitCallback默认被包在一个 1000ms 的超时竞态函数createFunctionWithTimeout中src/index.js如果 Analytics 库加载失败或命中迟迟没有送达回调也一定会在超时后被调用一次避免业务逻辑被无限阻塞。该机制与 Google Analytics 官方文档中“处理超时Handling Timeouts”的建议一致。Troubleshooting常见问题排查没有任何行为被追踪检查 tracking ID确认gatsby-config.js中配置的 tracking ID 格式正确应为trackingId: UA-111111111-1这样的格式。ID 错误或缺失时SSR 阶段根本不会生成追踪脚本。确保插件与脚本最先加载追踪脚本没有正确注入 DOM 时把该插件移到gatsby-config.js的plugins数组第一位并设置head: true将脚本放入headmodule.exports { siteMetadata: { /* your metadata */ }, plugins: [ // Make sure this plugin is first in the array of plugins { resolve: gatsby-plugin-google-analytics, options: { trackingId: UA-111111111-1, // this option places the tracking script into the head of the DOM head: true, // other options }, }, ], // other plugins }此外请确认你查看的是生产构建产物gatsby build后gatsby serve因为开发模式gatsby develop下插件是被主动禁用的。小结gatsby-plugin-google-analytics通过SSR 注入脚本 浏览器端路由监听 导出组件/函数三件套让 Gatsby 站点的 Google Analytics 接入几乎零成本配置一个trackingId即可获得自动 pageview开启enableWebVitalsTracking即可采集真实用户体验指标借助OutboundLink与trackCustomEvent可以精准覆盖外链与业务事件的埋点。理解 src/gatsby-ssr.js、src/gatsby-browser.js 与 src/index.js 三份核心源码也能帮助你在排查问题时快速定位脚本注入与事件上报的每个环节。若你正在开启新项目建议优先评估仓库中的替代方案 gatsby-plugin-google-gtag以获得基于gtag.js的长期支持。【免费下载链接】gatsbyReact-based framework with performance, scalability, and security built in.项目地址: https://gitcode.com/gh_mirrors/ga/gatsby创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考