Redux Beacon：用状态流驱动 Google Analytics 埋点

1. 项目概述：为什么在 React/Redux 应用里做 Google Analytics 不该是“写几个 trackEvent 就完事”的事

你刚接手一个上线三个月的电商 React 应用，老板问：“用户都在哪流失？加购后没下单的关键路径是什么？首页 Banner 点击率到底有没有提升？”你打开 GA4 报表，发现事件数据稀稀拉拉——只有手动埋点的几个按钮点击，页面浏览量对得上，但“加入购物车”“填写收货地址”“支付成功”这些核心转化节点全靠猜。更糟的是，团队里三个前端轮着改代码，有人用gtag('event', ...)，有人调analytics.track()，还有人直接在 useEffect 里塞window.gaq.push(...)，埋点逻辑散落在十几个组件里，没人敢动，一改就崩。这不是个例，而是绝大多数 React/Redux 项目在接入 Google Analytics 时的真实困境：分析数据和业务逻辑被硬生生割裂，埋点变成维护噩梦，而不是决策依据。

这就是 “Google Analytics on your React/Redux App with Redux Beacon” 这个标题背后最痛的现实。它不是一个简单的“如何把 GA 脚本加进 index.html”的教程，而是一次架构级的重构思路——把用户行为分析，从零散、被动、易出错的手动埋点，升级为与应用状态流深度耦合、可预测、可复现、可测试的声明式追踪体系。核心关键词Google Analytics、React、Redux、Redux Beacon，每一个都指向一个关键环节：Google Analytics是目标数据平台；React是视图层，负责触发交互；Redux是状态中枢，记录了用户每一步操作的“真相”；而Redux Beacon，就是那个把“状态变化”自动翻译成“分析事件”的智能翻译官。它不关心你用的是函数组件还是类组件，不依赖 DOM 生命周期，只监听 store.dispatch 的每一次调用，只要 action 被发出，它就能精准捕获并映射为 GA 事件。这意味着，你的“加入购物车”逻辑写在cartSlice.js里，对应的 GA 事件也定义在那里；你的“用户登录成功” action type 是'AUTH_LOGIN_SUCCESS'，它的 GA 事件名、参数、是否触发 page_view，全部在同一个配置对象里声明。这种一致性，让埋点不再是开发后期的补丁，而是从需求评审阶段就嵌入产品设计的 DNA。

这个方案特别适合三类人：第一类是正在用 Redux（或 RTK）构建中大型应用的前端工程师，你们的状态管理已经很规范，缺的只是一个“状态到分析”的标准管道；第二类是技术负责人或数据产品经理，需要确保全站埋点口径统一、可审计、可回溯，避免市场部和研发部对着两套数据打架；第三类是正在准备 React 面试的开发者，尤其是被问到“如何设计可扩展的埋点系统”“Redux 中间件原理”“React + Redux 最佳实践”这类高阶问题时，Redux Beacon 的实现思路——基于 middleware 拦截 action、基于 meta 字段携带追踪元信息、基于 reducer 状态推导用户旅程——本身就是一份教科书级的答案。它不炫技，但足够扎实；不追求最新框架，却直击工程化落地的核心痛点。接下来，我们就从设计哲学、技术细节、实操步骤到踩坑实录，一层层剥开这个看似小众、实则极具启发性的方案。

2. 核心设计思路拆解：为什么是 Redux Beacon，而不是 useEffect 或自定义 Hook？

很多 React 开发者的第一反应是：“我直接在按钮的 onClick 里调用 gtag 不就行了吗？”或者更“高级”一点，“写个 useAnalytics hook，在组件里调用”。这两种方式在简单场景下确实能跑通，但一旦项目规模上来，就会暴露出根本性缺陷。而 Redux Beacon 的设计，恰恰是为了解决这些缺陷而生的。理解它“为什么是这个样子”，比记住怎么配置更重要。

2.1 缺陷一：埋点逻辑与业务逻辑强耦合，导致“改功能=改埋点=提心吊胆”

想象一个商品详情页的“立即购买”按钮。用 onClick 方式，代码可能是这样的：

// ProductDetail.jsx const handleBuyNow = () => { // 业务逻辑：跳转到结算页 navigate('/checkout', { state: { productId } }); // 埋点逻辑：发送 GA 事件 gtag('event', 'click_buy_now', { item_id: productId, item_name: productName, price: productPrice }); };

这看起来很清晰。但问题在于，当产品需求变更，比如要求“未登录用户点击后先弹登录框，登录成功再跳转”，业务逻辑会变成异步流程：

const handleBuyNow = async () => { if (!isLogin) { await showLoginModal(); } // 登录成功后，才执行跳转和埋点 navigate('/checkout', { state: { productId } }); gtag('event', 'click_buy_now', { /* ... */ }); // 这行代码现在可能执行多次或漏掉！ };

埋点代码的位置变得极其脆弱。它必须精确地放在所有可能的执行路径末尾，稍有不慎，数据就失真。而 Redux Beacon 的思路完全不同：它不关心按钮在哪、怎么触发，只关心“用户决定购买”这个事实是否被记录到了全局状态里。我们定义一个 action：

// actions/cartActions.js export const addToCart = (product) => ({ type: 'CART_ADD_ITEM', payload: product, meta: { analytics: { event: 'add_to_cart', params: { item_id: product.id } } } });

无论这个 action 是从 ProductDetail 组件 dispatch 的，还是从一个后台定时任务触发的，Redux Beacon 的 middleware 都会捕获它，并根据meta.analytics字段自动发送 GA 事件。业务逻辑和埋点逻辑彻底解耦，修改购买流程，完全不影响埋点的正确性。

2.2 缺陷二：无法捕获“非交互”状态变化，丢失关键用户旅程

GA 的核心价值在于还原用户旅程（User Journey）。但很多关键节点根本不是由用户点击触发的。比如：

• 用户在搜索框输入关键词，搜索结果列表自动更新（无显式按钮点击）；
• 页面加载后，根据用户地理位置自动切换语言和货币；
• 用户在表单中连续填写了 5 个字段，系统根据规则实时校验并显示提示。

这些“状态驱动”的行为，用 onClick 或 useEffect 埋点几乎无法覆盖。useEffect 可以监听 props 或 state 变化，但它只能看到“变化后的值”，看不到“变化的原因”——是用户输入导致的？是 API 返回数据导致的？还是路由参数变化导致的？而 Redux 的核心优势，就是它强制要求所有状态变化都必须通过明确的 action 来触发。action 就是那个“原因”的唯一信标。Redux Beacon 正是利用了这一点。它监听的是 action，而不是 DOM 或 state。所以，当一个SET_SEARCH_QUERYaction 被 dispatch，Beacon 就能立刻知道“用户开始搜索了”，并发送search事件；当一个UPDATE_USER_PREFERENCESaction 包含currency: 'JPY'，Beacon 就能发送user_preference_change事件。这种基于“意图”而非“结果”的埋点，才是构建完整用户旅程图谱的基础。

2.3 缺陷三：缺乏可测试性与可审计性，数据质量无法保障

在大型团队中，埋点数据是市场投放、产品迭代、A/B 测试的基石。如果埋点代码散落在几十个组件里，如何保证：

• 所有add_to_cart事件都携带了item_id和price这两个必填参数？
• page_view事件的page_title字段，是否总是取自当前路由的document.title，而不是某个组件的局部 state？
• 当产品经理要求“将所有‘注册成功’事件的 category 改为 ‘onboarding’”，如何快速、安全地完成全站修改？

用传统方式，答案是“人肉 grep + 逐个修改 + 手动回归测试”，效率低且风险高。而 Redux Beacon 的解决方案是“中心化配置”。所有事件映射规则都定义在一个或少数几个配置文件里：

// analytics/beaconConfig.js export const beaconConfig = { targets: [googleAnalyticsTarget], events: [ // 规则1：匹配所有 CART_* 类型的 action { predicate: action => action.type.startsWith('CART_'), event: (action) => ({ name: action.type.toLowerCase().replace('_', '_'), params: { ...action.payload, timestamp: Date.now() } }) }, // 规则2：专门处理登录成功 { predicate: action => action.type === 'AUTH_LOGIN_SUCCESS', event: () => ({ name: 'login', params: { method: 'email' } }) } ] };

这个配置本身就是一个可测试的 JavaScript 对象。你可以轻松地为它写单元测试：

test('CART_ADD_ITEM should map to add_to_cart event', () => { const action = { type: 'CART_ADD_ITEM', payload: { id: '123', price: 99.99 } }; const result = beaconConfig.events[0].event(action); expect(result.name).toBe('add_to_cart'); expect(result.params.id).toBe('123'); });

数据质量的保障，从此从“靠人盯”变成了“靠代码测”。

2.4 为什么不是其他方案？Redux Beacon 的不可替代性

市面上还有其他方案，比如react-ga4、@google-analytics/react，它们提供了 React Hooks 封装，用起来更“顺手”。但它们的本质，依然是“在组件里调用”，没有解决上述三大缺陷。而像redux-logger这样的经典 Redux middleware，虽然也监听 action，但它只做日志输出，不具备将 action 映射为第三方分析平台事件的能力。Redux Beacon 的独特价值，在于它精准地卡在了“Redux 生态”和“分析平台生态”的交汇点上：它是一个专为“状态驱动分析”而生的、轻量级、可插拔、可配置的中间件。它不侵入你的业务代码，不改变你的 Redux 使用习惯，只是在 store 创建时，像添加thunk一样，多加一个beaconMiddleware。它的存在感极低，但带来的工程收益极高——它让埋点这件事，第一次真正拥有了和业务逻辑同等的可维护性、可测试性和可演进性。

3. 核心细节解析与实操要点：从概念到代码，每一步都经得起推敲

理解了设计哲学，现在我们进入真正的“动手环节”。Redux Beacon 的核心并不复杂，但其中的每一个配置项、每一个约定，都有其深意。盲目复制粘贴配置，很容易在后续维护中踩坑。下面，我将结合一个真实的电商应用片段，详细拆解每一个关键细节。

3.1 基础依赖安装与 Store 初始化：不要跳过这一步

首先，确保你的项目已正确安装核心依赖。这里有一个极易被忽略的细节：Redux Beacon 的版本必须与你的 Redux 版本严格匹配。如果你用的是 Redux Toolkit (RTK)，即@reduxjs/toolkit，那么你必须使用redux-beacon@^4.0.0及以上版本，因为旧版本（v3.x）是为原生 Redux 设计的，与 RTK 的configureStoreAPI 不兼容。执行以下命令：

# 如果你用的是 RTK（强烈推荐） npm install redux-beacon @redux-beacon/google-analytics # 如果你用的是原生 Redux（不推荐，仅作说明） npm install redux-beacon@^3.0.0 @redux-beacon/google-analytics@^2.0.0

提示：@redux-beacon/google-analytics是官方提供的针对 GA4 的 target（目标平台），它封装了所有与 GA4 的通信细节，包括gtag的初始化、事件发送、配置参数等。你不需要自己写gtag('config', ...)，Beacon 会帮你搞定。

接下来是 Store 的初始化。这是最关键的一步，也是最容易出错的地方。很多人会把 Beacon middleware 加在applyMiddleware的错误位置，导致它无法捕获到所有 action。正确的做法是，将beaconMiddleware作为最后一个 middleware 加入，并且要确保它在thunk或redux-saga等异步 middleware 之后。因为thunk会把一个函数 action 转换成一个普通 action，Beacon 必须在转换完成后才能捕获到最终的、可映射的 action。

// store/index.js import { configureStore } from '@reduxjs/toolkit'; import { createLogger } from 'redux-logger'; import { createBeaconMiddleware } from 'redux-beacon'; import { googleAnalytics } from '@redux-beacon/google-analytics'; import { beaconConfig } from './analytics/beaconConfig'; import rootReducer from './rootReducer'; // 1. 创建 Beacon middleware 实例 const beaconMiddleware = createBeaconMiddleware( googleAnalytics(window.gtag), // 传入全局 gtag 函数 beaconConfig ); // 2. 创建 store，注意 middleware 的顺序 export const store = configureStore({ reducer: rootReducer, middleware: (getDefaultMiddleware) => getDefaultMiddleware() .concat(beaconMiddleware) // 必须放在最后！ .concat(createLogger()), // logger 也放后面，方便看到 Beacon 发送的事件 });

注意：googleAnalytics(window.gtag)这一行，window.gtag必须在store创建之前就已经存在。这意味着你需要在index.html的<head>中，或者在index.js的最顶部，先加载 GA4 的全局脚本：

<!-- index.html --> <script async src="https://www.googletagmanager.com/gtag/js?id=G-XXXXXXXXXX"></script> <script> window.dataLayer = window.dataLayer || []; function gtag(){dataLayer.push(arguments);} gtag('js', new Date()); gtag('config', 'G-XXXXXXXXXX'); // 这里填你的 GA4 Measurement ID </script>

3.2 Beacon 配置详解：predicate、event、transform的精妙配合

beaconConfig.js是整个方案的“大脑”。它的结构非常清晰，主要包含targets（目标平台）和events（事件规则数组）。我们来逐行解读一个生产环境可用的配置：

// analytics/beaconConfig.js import { googleAnalytics } from '@redux-beacon/google-analytics'; // 定义一个通用的 transform 函数，用于标准化所有事件的参数 const standardizeParams = (params) => ({ ...params, // 添加一个统一的事件来源标识，便于在 GA 后台筛选 event_source: 'redux_beacon', // 添加时间戳，GA4 本身有 timestamp_micros，但加上这个更直观 timestamp: new Date().toISOString(), }); export const beaconConfig = { // targets 数组可以包含多个，比如同时发给 GA4 和 Sentry targets: [ googleAnalytics(window.gtag, { // 这里可以覆盖 GA4 的全局配置 config: { send_page_view: false, // 关键！禁用自动 page_view，我们自己控制 } }) ], // events 是一个规则数组，Beacon 会按顺序遍历，找到第一个 predicate 为 true 的规则 events: [ // 规则1：捕获所有页面浏览（page_view） { // predicate：一个函数，返回 true 则应用此规则 predicate: (action) => action.type === 'ROUTER_LOCATION_CHANGED', // event：一个函数，返回要发送的 GA 事件对象 event: (action) => ({ name: 'page_view', params: standardizeParams({ page_location: action.payload.location.href, page_path: action.payload.location.pathname, page_title: document.title, // 从路由状态中提取自定义维度，比如 A/B 测试分组 ab_test_group: action.payload.state?.abTestGroup || 'control' }) }) }, // 规则2：捕获所有购物车操作 { predicate: (action) => action.type.startsWith('CART_'), event: (action) => { // 根据不同的 CART_* action type，映射为不同的 GA 事件名 const gaEventMap = { 'CART_ADD_ITEM': 'add_to_cart', 'CART_REMOVE_ITEM': 'remove_from_cart', 'CART_UPDATE_QUANTITY': 'view_cart' }; return { name: gaEventMap[action.type] || 'cart_action', params: standardizeParams({ item_id: action.payload?.id, item_name: action.payload?.name, price: action.payload?.price, quantity: action.payload?.quantity }) }; } }, // 规则3：捕获用户登录/登出 { predicate: (action) => ['AUTH_LOGIN_SUCCESS', 'AUTH_LOGOUT'].includes(action.type), event: (action) => ({ name: action.type === 'AUTH_LOGIN_SUCCESS' ? 'login' : 'logout', params: standardizeParams({ method: action.payload?.method || 'unknown' }) }) } ] };

这个配置里有几个关键技巧：

1. predicate的顺序很重要：Beacon 是“找到第一个匹配的就停止”，所以要把最具体的规则（如ROUTER_LOCATION_CHANGED）放在前面，把最宽泛的规则（如CART_*）放在后面。否则，一个CART_ADD_ITEMaction 可能会被前面的通用规则误匹配。
2. event函数的灵活性：它不仅仅是一个静态对象，而是一个可以执行任意逻辑的函数。上面的例子中，我们根据action.type动态计算name，并从action.payload中安全地提取参数（用了可选链?.防止报错）。这让你可以处理非常复杂的映射逻辑。
3. transform的缺失与替代：新版 Redux Beacon（v4+）移除了transform配置项，转而鼓励你在event函数内部进行参数处理。这更符合函数式编程思想，也让你的逻辑更内聚、更易测试。

3.3 在 Action Creator 中注入元信息：meta字段的正确用法

前面我们一直提到meta字段，它是 Redux Beacon 的“魔法开关”。但它的用法有严格规范。meta必须是一个 plain object（纯对象），不能是函数或 class 实例。而且，meta.analytics是 Beacon 识别的约定俗成的 key。一个典型的、符合规范的 action creator 如下：

// features/product/productSlice.js (RTK Slice) import { createSlice } from '@reduxjs/toolkit'; export const productSlice = createSlice({ name: 'product', initialState: { /* ... */ }, reducers: { // 这是一个同步 reducer addToCart: (state, action) => { // 业务逻辑：更新 state state.cartItems.push(action.payload); } }, // extraReducers 用于处理异步 thunk extraReducers: (builder) => { builder .addCase(fetchProduct.pending, (state, action) => { state.loading = true; }) .addCase(fetchProduct.fulfilled, (state, action) => { state.loading = false; state.currentProduct = action.payload; }) .addCase(fetchProduct.rejected, (state, action) => { state.loading = false; state.error = action.error.message; }); } }); // 这是关键：在 dispatch action 时，通过 meta 注入分析信息 export const fetchAndTrackProduct = (productId) => (dispatch, getState) => { // 1. 先 dispatch 一个 "fetch started" 事件，用于埋点 dispatch({ type: 'PRODUCT_FETCH_START', payload: { productId }, meta: { analytics: { event: 'view_item', // 直接指定 GA 事件名 params: { item_id: productId } // 直接指定参数 } } }); // 2. 然后执行真正的异步请求 return dispatch(fetchProduct(productId)); }; // 导出 action creators export const { addToCart } = productSlice.actions;

注意：addToCart这个同步 action，我们并没有在它里面加meta，因为它的meta会在dispatch(addToCart(...))的时候，由调用方动态传入。而fetchAndTrackProduct这个 thunk，则是在内部dispatch时，主动构造了一个带meta的 action。两种方式都可行，选择哪种取决于你的团队规范。我个人更倾向于后者，因为它把“何时埋点”和“埋什么点”的逻辑，都封装在了业务逻辑内部，调用方无需关心。

4. 实操过程与核心环节实现：从零开始，搭建一个可运行的 Demo

纸上得来终觉浅，绝知此事要躬行。现在，让我们把前面所有的理论，整合成一个最小但可运行的 React/Redux 应用 Demo。这个 Demo 将包含：一个简单的商品列表页、一个购物车状态、以及完整的 GA4 埋点。你可以把它当作一个模板，直接复制到自己的项目中。

4.1 初始化项目与基础结构

我们使用create-react-app（CRA）作为起点，因为它对新手友好，且能快速验证效果。执行以下命令：

npx create-react-app redux-beacon-demo --template typescript cd redux-beacon-demo npm install @reduxjs/toolkit react-router-dom redux-beacon @redux-beacon/google-analytics

然后，创建基本的目录结构：

src/ ├── store/ │ ├── index.ts │ ├── analytics/ │ │ └── beaconConfig.ts │ └── rootReducer.ts ├── features/ │ ├── product/ │ │ ├── productSlice.ts │ │ └── ProductList.tsx │ └── cart/ │ ├── cartSlice.ts │ └── CartSummary.tsx └── App.tsx

4.2 编写核心 Slice：Product 和 Cart

我们先编写productSlice.ts，它负责管理商品列表和“查看商品详情”的动作：

// features/product/productSlice.ts import { createSlice, PayloadAction } from '@reduxjs/toolkit'; interface Product { id: string; name: string; price: number; } const initialState: { products: Product[]; selectedId: string | null } = { products: [ { id: 'p1', name: 'iPhone 15', price: 7999 }, { id: 'p2', name: 'MacBook Pro', price: 15999 } ], selectedId: null }; export const productSlice = createSlice({ name: 'product', initialState, reducers: { selectProduct: (state, action: PayloadAction<string>) => { state.selectedId = action.payload; // 这里我们不加 meta，因为 selectProduct 是一个 UI 状态，不是用户意图 // 真正的“查看商品”意图，应该在导航到详情页时触发 } } }); export const { selectProduct } = productSlice.actions; export default productSlice.reducer;

接着是cartSlice.ts，它管理购物车，并在addItem时注入meta：

// features/cart/cartSlice.ts import { createSlice, PayloadAction } from '@reduxjs/toolkit'; interface CartItem extends Product { quantity: number; } const initialState: { items: CartItem[] } = { items: [] }; export const cartSlice = createSlice({ name: 'cart', initialState, reducers: { addItem: (state, action: PayloadAction<Product>) => { const existing = state.items.find(item => item.id === action.payload.id); if (existing) { existing.quantity += 1; } else { state.items.push({ ...action.payload, quantity: 1 }); } } } }); // 这是关键：导出一个带 meta 的 action creator export const addItemWithAnalytics = (product: Product) => ({ type: 'cart/addItem', payload: product, meta: { analytics: { event: 'add_to_cart', params: { item_id: product.id, item_name: product.name, price: product.price, currency: 'CNY' } } } }); export const { addItem } = cartSlice.actions; export default cartSlice.reducer;

4.3 构建 Beacon 配置与 Store

现在，我们来编写store/analytics/beaconConfig.ts：

// store/analytics/beaconConfig.ts import { googleAnalytics } from '@redux-beacon/google-analytics'; // 我们在这里定义一个简单的 transform，用于添加通用参数 const addCommonParams = (params: Record<string, any>) => ({ ...params, app_version: '1.0.0', environment: process.env.NODE_ENV === 'production' ? 'prod' : 'dev' }); export const beaconConfig = { targets: [ googleAnalytics(window.gtag, { config: { send_page_view: false } }) ], events: [ // 页面浏览事件 { predicate: (action) => action.type === 'ROUTER_LOCATION_CHANGED', event: (action) => ({ name: 'page_view', params: addCommonParams({ page_location: action.payload?.location?.href || '', page_path: action.payload?.location?.pathname || '', page_title: document.title }) }) }, // 购物车添加事件 { predicate: (action) => action.type === 'cart/addItem', event: (action) => ({ name: 'add_to_cart', params: addCommonParams(action.payload) }) } ] };

最后，是store/index.ts，它将所有部分串联起来：

// store/index.ts import { configureStore } from '@reduxjs/toolkit'; import { createBeaconMiddleware } from 'redux-beacon'; import { googleAnalytics } from '@redux-beacon/google-analytics'; import { beaconConfig } from './analytics/beaconConfig'; import productReducer from '../features/product/productSlice'; import cartReducer from '../features/cart/cartSlice'; // 创建 Beacon middleware const beaconMiddleware = createBeaconMiddleware( googleAnalytics(window.gtag), beaconConfig ); // 创建 store export const store = configureStore({ reducer: { product: productReducer, cart: cartReducer }, middleware: (getDefaultMiddleware) => getDefaultMiddleware().concat(beaconMiddleware) }); export type RootState = ReturnType<typeof store.getState>; export type AppDispatch = typeof store.dispatch;

4.4 在组件中使用：ProductList 和 CartSummary

现在，我们来编写ProductList.tsx，它将展示商品列表，并在点击“加入购物车”时 dispatch 带meta的 action：

// features/product/ProductList.tsx import React from 'react'; import { useDispatch, useSelector } from 'react-redux'; import { selectProduct } from '../product/productSlice'; import { addItemWithAnalytics } from '../cart/cartSlice'; import { RootState } from '../../store'; const ProductList: React.FC = () => { const dispatch = useDispatch(); const products = useSelector((state: RootState) => state.product.products); const handleAddToCart = (product: { id: string; name: string; price: number }) => { // 这里 dispatch 的是 addItemWithAnalytics，它内部已经包含了 meta dispatch(addItemWithAnalytics(product)); // 可以加一个 UI 反馈 alert(`已将 ${product.name} 加入购物车！`); }; return ( <div> <h2>商品列表</h2> {products.map(product => ( <div key={product.id}> <h3>{product.name}</h3> <p>¥{product.price}</p> <button onClick={() => handleAddToCart(product)}> 加入购物车 </button> </div> ))} </div> ); }; export default ProductList;

CartSummary.tsx则用来显示当前购物车内容：

// features/cart/CartSummary.tsx import React from 'react'; import { useSelector } from 'react-redux'; import { RootState } from '../../store'; const CartSummary: React.FC = () => { const cartItems = useSelector((state: RootState) => state.cart.items); return ( <div> <h2>购物车 ({cartItems.length} 件)</h2> {cartItems.length === 0 ? ( <p>购物车是空的</p> ) : ( <ul> {cartItems.map(item => ( <li key={item.id}> {item.name} x{item.quantity} - ¥{(item.price * item.quantity).toFixed(2)} </li> ))} </ul> )} </div> ); }; export default CartSummary;

4.5 集成 Router 并触发页面浏览事件

为了让ROUTER_LOCATION_CHANGED这个 action 被 dispatch，我们需要集成react-router-dom。在App.tsx中：

// App.tsx import React from 'react'; import { BrowserRouter, Routes, Route, useLocation, Navigate } from 'react-router-dom'; import { Provider } from 'react-redux'; import { store } from './store'; import ProductList from './features/product/ProductList'; import CartSummary from './features/cart/CartSummary'; // 这是一个自定义 Hook，用于在路由变化时 dispatch action const RouterListener: React.FC = () => { const location = useLocation(); React.useEffect(() => { // 每次路由变化，dispatch 一个 ROUTER_LOCATION_CHANGED action store.dispatch({ type: 'ROUTER_LOCATION_CHANGED', payload: { location } }); }, [location]); return null; }; const App: React.FC = () => { return ( <Provider store={store}> <BrowserRouter> <RouterListener /> <Routes> <Route path="/" element={<ProductList />} /> <Route path="/cart" element={<CartSummary />} /> <Route path="*" element={<Navigate to="/" replace />} /> </Routes> </BrowserRouter> </Provider> ); }; export default App;

至此，整个 Demo 已经完成。启动应用 (npm start)，打开浏览器开发者工具的 Network 标签页，然后点击“加入购物车”按钮。你应该能看到一个https://www.google-analytics.com/g/collect?...的请求，其中包含了add_to_cart事件的所有参数。同时，在 Console 中，你也能看到redux-logger输出的 action 日志，确认addItemWithAnalytics被正确 dispatch。

5. 常见问题与排查技巧实录：那些只有亲手踩过才知道的坑

在将 Redux Beacon 集成到真实项目的过程中，我遇到过太多“理论上应该没问题，但就是不工作”的情况。这些问题往往不会出现在官方文档里，但却是每个实践者都必须跨越的门槛。下面，我将分享一份基于真实项目经验的“避坑指南”，它涵盖了从环境配置到数据验证的全流程。

5.1 问题一：GA4 后台看不到任何事件，Network 请求里也没有g/collect

这是最常见、也最让人抓狂的问题。排查思路必须系统化，不能只盯着 Beacon 配置。

第一步：确认 GA4 脚本是否加载成功打开浏览器开发者工具的 Console，输入window.gtag。如果返回undefined，说明 GA4 的全局脚本根本没有加载。检查index.html中的<script>标签是否拼写错误，gtag的config是否使用了正确的 Measurement ID（格式是G-XXXXXXXXXX，不是UA-XXXXXXXXX-X）。一个快速验证方法是，在 Console 里直接执行gtag('event', 'test_event')，如果能看到 Network 请求，说明脚本没问题。

第二步：确认beaconMiddleware是否被正确添加在store/index.ts中，检查middleware的拼写。常见的错误是写成了middlware（少了一个e），或者把beaconMiddleware写在了getDefaultMiddleware()之前。最可靠的验证方法是，在beaconConfig.events的predicate函数里加一个console.log：

predicate: (action) => { console.log('Beacon is checking action:', action.type); // 加这一行 return action.type === 'cart/addItem'; }

然后点击按钮，如果 Console 里没有任何输出，说明 middleware 根本没生效。

第三步：确认window.gtag是否在createBeaconMiddleware时被正确传入这是一个经典的“时序问题”。createBeaconMiddleware(googleAnalytics(window.gtag), ...)这行代码，必须在window.gtag已经被定义之后执行。如果store/index.ts是在index.html的<script>标签之前被 import 的，window.gtag就是undefined。解决方案是，把 GA4 的<script>标签放在<head>的最顶部，并确保它在任何 JS bundle 加载之前执行。或者，更稳妥的做法是，在store/index.ts中，用一个延迟函数来确保gtag可用：

// store/index.ts const getGtag = () => { if (typeof window !== 'undefined' && window.gtag) { return window.gtag; } // 如果 gtag 还没加载，等待 100ms 后重试（最多重试 5 次） return new Promise((resolve) => { let attempts = 0; const tryResolve = () => { if (window.gtag) { resolve(window.gtag); } else if (attempts < 5) { attempts++; setTimeout(tryResolve, 100); } else { console.error('Failed to load gtag after 5 attempts'); resolve(null); } }; tryResolve(); }); }; // 在创建 middleware 时 getGtag().then(gtag => { if (gtag) { const beaconMiddleware = createBeaconMiddleware( googleAnalytics(gtag), beaconConfig ); // ... rest of store setup } });

5.2 问题二：事件参数缺失或错误，比如item_id总是undefined

这通常是因为action.payload的结构和你在event函数中期望的结构不一致。例如，你的addItemWithAnalyticsaction 的payload是一个Product对象，但你在event函数里却写了action.payload.id，而实际上Product对象的 key 是productId。

排查技巧：在event函数里加console.log

event: (action) => { console.log('Raw