如何在Next.js服务端渲染（SSR）中正确使用Mixpanel？

你的问题核心在于**mixpanel-browser是浏览器端专属SDK**，直接在服务端的getServerSideProps里调用会因为缺少浏览器环境（比如window对象）而失效，甚至报错。下面分场景给出正确的实现方式：

一、客户端（浏览器）的Mixpanel集成 #

如果是追踪用户在浏览器内的行为，应该在客户端环境初始化和调用Mixpanel，推荐在_app.tsx中通过useEffect实现：

import { useEffect } from 'react';
import mixpanel from 'mixpanel-browser';
import { AppProps } from 'next/app';

function MyApp({ Component, pageProps }: AppProps) {
  useEffect(() => {
    // 仅在客户端初始化Mixpanel
    mixpanel.init('MY_MIXPANEL_TOKEN', {
      debug: process.env.NODE_ENV === 'development', // 开发环境开启调试
      track_pageview: false // 手动控制页面浏览追踪，避免重复
    });

    // 追踪初始页面访问
    mixpanel.track('Page view', {
      page: window.location.pathname,
      user: pageProps.session?.user?.email
    });

    // 路由切换时追踪页面变化
    const handleRouteChange = (url: string) => {
      mixpanel.track('Page view', {
        page: url,
        user: pageProps.session?.user?.email
      });
    };

    // 监听Next.js路由事件
    typeof window !== 'undefined' && window.addEventListener('routeChangeComplete', handleRouteChange);

    return () => {
      window.removeEventListener('routeChangeComplete', handleRouteChange);
    };
  }, [pageProps.session]);

  return <Component {...pageProps} />;
}

export default MyApp;

二、服务端（getServerSideProps）的Mixpanel追踪 #

如果需要在服务端触发事件（比如页面渲染前的操作），要使用Mixpanel的Node.js SDK，而非浏览器SDK：

1. 先安装Node.js SDK：

npm install @mixpanel/mixpanel-node
# 或
yarn add @mixpanel/mixpanel-node

2. 在getServerSideProps中使用：

import { GetSessionParams, getSession } from "next-auth/client";
import Mixpanel from '@mixpanel/mixpanel-node';

export async function getServerSideProps(context: GetSessionParams | undefined) {
  const session = await getSession(context);

  // 初始化服务端Mixpanel实例
  const mixpanel = Mixpanel.init('MY_MIXPANEL_TOKEN');

  // 服务端追踪事件
  mixpanel.track('Server-side Page view', {
    page: '/auth/login',
    user: session?.user?.email,
    ip: context?.req?.headers['x-forwarded-for'] || context?.req?.socket.remoteAddress // 可选：记录用户IP
  });

  if (session) {
    return {
      redirect: {
        destination: '/',
        permanent: false
      }
    };
  }

  return {
    props: {
      session
    }
  };
}

三、关键注意事项 #

• 环境区分：永远不要在服务端环境调用mixpanel-browser，也不要在客户端用Node.js SDK。
• 用户标识：如果需要关联用户，客户端可以用mixpanel.identify(user_id)，服务端可以在追踪时传入distinct_id参数。
• 避免重复初始化：客户端的初始化逻辑要放在useEffect里，确保只在浏览器加载时执行一次。
• 调试模式：开发环境开启debug: true，可以在控制台查看Mixpanel的请求日志，方便排查问题。

内容的提问来源于stack exchange，提问作者Zohaib Tariq