企业官网建设流程全解析

Cloudflare Zaraz 实战模式指南：SPA 追踪、电商漏斗与 Worker 集成最佳实践

【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills

本篇技术指南以 patterns.md 为骨架，系统讲解 Cloudflare Zaraz 在真实业务中的高频落地模式：单页应用（SPA）页面追踪、用户身份识别、电商转化漏斗、A/B 测试埋点、与 Cloudflare Workers 的深度集成（Context Enrichers / Worker Variables），以及从 GTM 迁移的对照清单。读完本文，你将能够用zaraz全局对象在浏览器端完成从事件采集、用户画像到转化归因的完整埋点方案，并知道何时该用 Workers 补齐服务端能力。

一、先读懂 Zaraz 的运行模型

Cloudflare Zaraz 是一款在边缘（Edge）执行的服务端标签管理器：第三方脚本（分析、广告、聊天、营销工具）不再由浏览器直接加载，而是通过 Cloudflare 的网络在服务端代跑，站点只发起一次统一的 HTTP 请求，实现零客户端脚本开销。本仓库的 README.md 将其核心特性概括为四条：

• 服务端执行：脚本运行在 Cloudflare 边缘而非用户浏览器；
• 单次请求：所有工具经由同一个端点加载；
• 隐私优先：发往第三方工具的数据可控；
• 无客户端 JS 开销：对浏览器性能影响最小。

理解这一模型是掌握下面所有模式的前提：zaraz全局对象只是把事件“递交”给边缘，真正的工具执行、事件映射与数据转发都在服务端完成。因此事件调用都是“即发即忘”（fire-and-forget）的，异步批量上报，详见 api.md。

二、SPA 页面追踪：从“无代码”到手动埋点

单页应用（React / Vue / Next.js）的路由切换不触发整页刷新，传统的 Pageview 触发器只会统计首次加载。Zaraz 为此提供了两条路径。

2.1 首选：History Change 触发器（零代码）

在 Cloudflare 控制台的 Zaraz 配置中创建History Change类型触发器即可，无需任何内联代码，Zaraz 会自动探测路由变化：

Type: History Change Event: pageview

该触发器会在pushState、replaceState以及 hash 变化时自动触发，因此基于 History API 的主流前端路由（React Router、Vue Router history 模式等）开箱即用，不需要手动埋点。这是官方推荐做法，详见 configuration.md 的“History Change (SPA)”小节。

2.2 备选：手动追踪（React/Vue/Next.js）

当需要携带更精细的页面信息，或路由场景特殊（例如 hash 路由）时，可在路由变化处手动调用：

// On route change zaraz.track('pageview', { page_path: pathname, page_title: document.title });

对于 React，正确的做法是结合useLocation与useEffect，并把location放入依赖数组，确保每次路由变化都触发：

const location = useLocation(); useEffect(() => { zaraz.track('pageview', { page_path: location.pathname }); }, [location]); // Include dependency

对于 hash 路由（#/path），History Change 触发器不会覆盖，需要监听hashchange事件手动上报：

window.addEventListener('hashchange', () => { zaraz.track('pageview', { page_path: location.pathname + location.hash }); });

这两段修正代码同样来自仓库的 gotchas.md，是 SPA 追踪“事件不触发”的常见修复方案。

三、用户身份识别：zaraz.set 的会话级属性

zaraz.set()用于写入用户属性，这些属性会在当前页面会话（page session）内持续存在，用于用户识别与人群细分。典型登录/登出流程如下：

// Login zaraz.set({ userId: user.id, email: user.email, plan: user.plan }); zaraz.track('login', { method: 'oauth' }); // Logout - set to null (cannot clear) zaraz.set('userId', null);

注意两个关键点：

• zaraz.set同时支持键值对形式zaraz.set('userId', value)和对象形式zaraz.set({...})两种签名，对应 api.md 中 TypeScript 类型定义的两个重载；
• 属性无法被清除（cannot clear），登出时只能将其置为null——这是隐私合规设计中需要留意的行为。

另外，属性按页会话持久化，每次页面加载都需要重新 set；嵌套访问形如{{client.__zarazTrack.user.plan}}（见 gotchas.md 的 Data Layer 小节）。

四、电商转化漏斗：zaraz.ecommerce 全流程埋点

Zaraz 为电商场景提供专用 APIzaraz.ecommerce(event, properties)，覆盖从浏览到下单的完整漏斗，工具端会自动映射到 GA4、Facebook CAPI 等广告平台，实现转化归因：

完整的调用示例（含商品列表结构）：

zaraz.ecommerce('Product Viewed', { product_id: 'SKU123', name: 'Widget', price: 49.99 }); zaraz.ecommerce('Product Added', { product_id: 'SKU123', quantity: 2, price: 49.99 }); zaraz.ecommerce('Order Completed', { order_id: 'ORD-789', total: 149.98, currency: 'USD', products: [{ product_id: 'SKU123', quantity: 2, price: 49.99 }] });

官方支持的电商事件全集还包括Product Removed、Cart Viewed等，api.md 中列出了完整事件列表：Product Viewed、Product Added、Product Removed、Cart Viewed、Checkout Started、Order Completed。建议在接入时以这组标准事件名为准，便于工具自动映射。

五、A/B 测试实验埋点

将实验标识与变体信息写入用户属性，再配合事件上报，即可打通实验层与转化层的数据：

zaraz.set('experiment_checkout', variant); zaraz.track('experiment_viewed', { experiment_id: 'checkout', variant }); // On conversion zaraz.track('experiment_conversion', { experiment_id, variant, value });

要点：实验信息用zaraz.set持久化到会话，浏览与转化事件分别上报，转化事件携带value便于在分析端计算实验收益。

六、Worker 集成：把服务端能力注入 Zaraz

这是 Zaraz 与 Cloudflare Workers 生态衔接的桥头堡，包含两种官方模式。

6.1 Context Enricher：工具执行前改写上下文

Context Enricher 是一个部署在 Workers 上的 HTTP 端点，Zaraz 会在工具执行前调用它，允许你修改发给各工具的上下文（context）。典型场景是把服务端才能拿到的地域信息注入上下文：

export default { async fetch(request, env) { const body = await request.json(); body.system.userRegion = request.cf?.region; return Response.json(body); } };

配置入口：Zaraz > Settings > Context Enrichers。这是“敏感数据 / 服务端数据”的处理推荐位置——不要让敏感逻辑暴露在浏览器端，而是放在 Workers 中计算后再注入。

6.2 Worker Variables：服务端动态计算变量

Worker Variables 允许在服务端动态计算值，并在 Zaraz 的触发器条件、工具配置中以{{worker.variable_name}}的形式引用。适合价格、库存、会员等级等需要实时计算的数据，与系统属性（如{{system.page.url}}）并列使用。

6.3 何时不该依赖 Zaraz

仓库的 gotchas.md 明确指出以下场景不应使用 Zaraz，应直接使用 Workers：

• 服务端到服务端（server-to-server）的追踪；
• 需要实时双向通信的场景；
• 二进制数据传输；
• 认证/鉴权流程。

判断原则可参考 README.md：当需要构建自定义服务端追踪逻辑、完全掌控数据处理、或 Zaraz 工具库无法满足需求时，直接写 Workers。

七、从 GTM 迁移：概念对照清单

如果你正从 Google Tag Manager（GTM）迁移到 Zaraz，下面这张映射表可以快速对齐心智模型（同样来自 patterns.md）：

补充说明：

• 变量层面，GTM 内置变量在 Zaraz 中对应的是系统属性（Zaraz Context），除上表外还包括{{system.page.referrer}}、{{system.device.ip}}、{{system.device.userAgent}}、{{system.device.language}}、{{system.cookies.name}}等，完整列表见 api.md 的“System Properties (Triggers)”小节；
• 触发器层面，Zaraz 的触发器类型为 Pageview、Click、Form Submission、History Change、Variable Match 五类（见 configuration.md），与 GTM 触发器一一对应，Click 触发器用 CSS 选择器定位元素并可用{{system.clickElement.text}}这类动态属性。

八、综合最佳实践清单

1. 优先使用控制台触发器而非内联代码——配置化的触发器可维护性更高，非技术人员也能管理；
2. SPA 站点开启 History Change 触发器——无需手动代码即可覆盖绝大多数路由场景；
3. 调试开启zaraz.debug = true——实时查看事件与已加载工具，console.log(zaraz.tools)可列出当前加载的工具列表，zaraz.consent.getAll()可检查各目的（purpose）的授权状态；
4. 尽早实现同意管理（GDPR/CCPA）——在控制台配置目的（analytics、marketing 等），将工具映射到目的，并设置“未获同意前不加载”；
5. 敏感数据/服务端数据使用 Context Enrichers 处理——避免在浏览器端暴露业务敏感逻辑。

关于性能与边界，gotchas.md 提醒：工具数量超过 50 个会拖慢页面、事件载荷应控制在 100KB 以内、API 速率上限为 1000 次/秒、同意目的最多 20 个。这些硬性限制是方案设计时必须留意的边界。

九、进一步阅读

本指南对应的完整参考体系位于 references/zaraz/，按任务阅读更高效：

• 想了解zaraz全局对象全部方法（track/set/ecommerce/consent/debug/ cookie 方法）与 TypeScript 类型定义 → api.md；
• 想在控制台完成工具接入、触发器与同意管理配置 → configuration.md；
• 遇到事件不触发、同意问题、工具特有坑（GA4 延迟、Facebook Pixel ID 需纯数字、Google Ads 需send_to）→ gotchas.md；
• 想从全局把握“何时用 Zaraz、何时直接用 Workers”的决策 → README.md。

此外，本仓库的 SKILL.md 将 Zaraz 归类于“媒体与内容（Media & Content）”产品线，可作为在整个 Cloudflare 部署方案中定位 Zaraz 的入口。

【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills