如何在Laravel 10+Inertia+React SSR项目中集成react-ga4？

一、初始化代码的放置位置 #

先安装react-ga4包，之后在app.jsx中完成初始化。由于项目启用了SSR，服务器端不存在window对象，必须先判断当前是否处于浏览器环境，再执行GA初始化逻辑。

修改后的app.jsx代码如下：

import './bootstrap';
import '../css/app.css';
import ReactGA from 'react-ga4'; // 导入react-ga4

import { createRoot } from 'react-dom/client';
import { createInertiaApp } from '@inertiajs/react';
import { resolvePageComponent } from 'laravel-vite-plugin/inertia-helpers';

const appName = window.document.getElementsByTagName('title')[0]?.innerText || 'Laravel';

createInertiaApp({
    title: (title) => `${title} - ${appName}`,
    resolve: (name) => resolvePageComponent(`./Pages/${name}.jsx`, import.meta.glob('./Pages/**/*.jsx')),
    setup({ el, App, props }) {
        // 仅在浏览器环境初始化GA
        if (typeof window !== 'undefined') {
            ReactGA.initialize('你的GA测量ID');
            // 可选：初始化时发送一次页面浏览事件
            ReactGA.send({ hitType: 'pageview', page: window.location.pathname });
        }

        const root = createRoot(el);
        root.render(<App {...props} />);
    },
    progress: {
        color: '#4B5563',
    },
});

二、页面浏览与自定义事件的发送 #

Inertia是单页应用，路由切换不会刷新页面，需要监听导航变化来发送页面浏览事件，最便捷的方式是在全局布局组件中处理：

1. 创建或修改全局布局组件（比如Layouts/AppLayout.jsx），加入路由监听逻辑：

import { useEffect } from 'react';
import ReactGA from 'react-ga4';
import { usePage } from '@inertiajs/react';

export default function AppLayout({ children }) {
    const { url } = usePage();

    useEffect(() => {
        // 仅在浏览器环境发送页面浏览事件
        if (typeof window !== 'undefined') {
            ReactGA.send({ hitType: 'pageview', page: url });
        }
    }, [url]);

    return (
        <div>
            {/* 你的布局内容 */}
            {children}
        </div>
    );
}

2. 自定义事件可在任意组件中直接调用，比如按钮点击场景：

import ReactGA from 'react-ga4';

function MyButton() {
    const handleClick = () => {
        if (typeof window !== 'undefined') {
            ReactGA.event({
                category: '交互',
                action: '按钮点击',
                label: '示例按钮'
            });
        }
        // 其他业务逻辑
    };

    return <button onClick={handleClick}>点击我</button>;
}

关键注意事项 #

• SSR环境判断：所有GA相关代码都要包裹在typeof window !== 'undefined'判断中，避免服务器端渲染时因找不到window对象报错。
• 全局路由监听：利用Inertia的usePage钩子获取当前URL，通过useEffect监听URL变化，自动发送页面浏览事件，无需在每个页面单独处理。

内容的提问来源于stack exchange，提问作者Tom Kur