instrument-integration

添加 PostHog SDK 集成

使用此技能为应用添加 PostHog SDK。在首次设置 PostHog 时，或审核需要初始化 PostHog 的 PR 时使用。涵盖 SDK 安装、Provider 设置和基本配置。支持任何框架或语言。

支持的框架和语言：Next.js、React、React Router、Vue、Nuxt、TanStack Start、SvelteKit、Astro、Angular、Django、Flask、FastAPI、Laravel、PHP、Ruby on Rails、Go、Elixir、Android、iOS、Swift、Flutter、React Native、Expo、Node.js 和 vanilla JavaScript。

说明

按顺序执行以下步骤：

步骤 1：分析代码库并检测平台。

查找依赖文件（package.json、pubspec.yaml、Podfile、Package.swift、requirements.txt、Gemfile、composer.json、go.mod、mix.exs 等），以确定框架和语言。

查找锁定文件（pnpm-lock.yaml、package-lock.json、yarn.lock、bun.lockb、go.sum、pubspec.lock、Podfile.lock、Package.resolved、mix.lock），以确定包管理器。

• 检查是否已有 PostHog 设置。如果已安装并初始化 PostHog，请勿修改其代码。告知用户并跳转至验证步骤。

步骤 2：研究集成方式。 2.1. 在下方找到与检测到的框架匹配的参考文件——它是 SDK 初始化、Provider 设置和配置模式的权威依据。现在阅读该文件。 2.2. 如果没有匹配的参考文件，请使用通用知识并进行网络搜索。优先搜索 posthog.com/docs。

步骤 3：安装 PostHog SDK。

• 为检测到的平台添加 PostHog SDK 包。请勿手动编辑 package.json——使用包管理器的安装命令。

步骤 4：初始化 PostHog。

• 按照框架参考，确定初始化的位置和方式。不同框架之间差异很大（例如，Next.js 15.3+ 使用 instrumentation-client.ts，Django 使用 AppConfig.ready()，Flask 使用 create_app()）。
• 如果框架需要，请设置 PostHog Provider／包装组件。

步骤 5：识别用户。

• 在登录和注册事件期间，在客户端添加 PostHog identify() 调用。
• 如果同时存在前端和后端，请使用 X-POSTHOG-DISTINCT-ID 和 X-POSTHOG-SESSION-ID 请求头，将客户端会话和 distinct ID 传递给服务端代码。

步骤 6：设置环境变量。

• 检查项目是否已配置 PostHog 环境变量（例如，在 .env、.env.local 或框架特定的环境文件中）。如果已有有效值，请跳过此步骤。
• 如果缺少 PostHog 项目令牌，请使用 PostHog MCP 服务的 projects-get 工具获取项目的 api_token。如果返回了多个项目，请询问用户要使用哪个项目。如果 MCP 服务未连接或未通过身份验证，请改为向用户索取 PostHog 项目令牌。
• 对于 PostHog 主机 URL：检查 projects-get MCP 响应中的 region 字段——US 对应 https://us.i.posthog.com，EU 对应 https://eu.i.posthog.com。如果 MCP 响应或现有项目配置中没有区域信息，请询问用户：“您使用的是 PostHog US Cloud 还是 EU Cloud？”不要假定使用 US Cloud。
• 按照框架的命名约定，将这些值写入适当的环境文件（例如，Next.js 使用 .env.local，其他框架使用 .env）。
• 在代码中引用这些环境变量，不要将其硬编码。

步骤 7：验证并清理。

• 检查项目是否存在错误。查找 package.json 中的类型检查或构建脚本。
• 确保创建的组件确实已被使用。
• 运行 package.json 中找到的任何 linter 或类似 prettier 的脚本，但仅限于本次会话中编辑或创建的文件。绝不要对整个项目代码库运行格式化或 lint。

参考文件

• references/EXAMPLE-next-app-router.md - next-app-router 示例项目代码
• references/EXAMPLE-next-pages-router.md - next-pages-router 示例项目代码
• references/EXAMPLE-react-react-router-6.md - react-react-router-6 示例项目代码
• references/EXAMPLE-react-react-router-7-framework.md - react-react-router-7-framework 示例项目代码
• references/EXAMPLE-react-react-router-7-data.md - react-react-router-7-data 示例项目代码
• references/EXAMPLE-react-react-router-7-declarative.md - react-react-router-7-declarative 示例项目代码
• references/EXAMPLE-react-vite.md - react-vite 示例项目代码
• references/EXAMPLE-nuxt-3-6.md - nuxt-3-6 示例项目代码
• references/EXAMPLE-nuxt-4.md - nuxt-4 示例项目代码
• references/EXAMPLE-vue-3.md - vue-3 示例项目代码
• references/EXAMPLE-react-tanstack-router-file-based.md - react-tanstack-router-file-based 示例项目代码
• references/EXAMPLE-react-tanstack-router-code-based.md - react-tanstack-router-code-based 示例项目代码
• references/EXAMPLE-tanstack-start.md - tanstack-start 示例项目代码
• references/EXAMPLE-sveltekit.md - sveltekit 示例项目代码
• references/EXAMPLE-astro-static.md - astro-static 示例项目代码
• references/EXAMPLE-astro-view-transitions.md - astro-view-transitions 示例项目代码
• references/EXAMPLE-astro-ssr.md - astro-ssr 示例项目代码
• references/EXAMPLE-astro-hybrid.md - astro-hybrid 示例项目代码
• references/EXAMPLE-angular.md - angular 示例项目代码
• references/EXAMPLE-javascript-node.md - javascript-node 示例项目代码
• references/EXAMPLE-javascript-web.md - javascript-web 示例项目代码
• references/EXAMPLE-django.md - django 示例项目代码
• references/EXAMPLE-flask.md - flask 示例项目代码
• references/EXAMPLE-fastapi.md - fastapi 示例项目代码
• references/EXAMPLE-python.md - python 示例项目代码
• references/EXAMPLE-laravel.md - laravel 示例项目代码
• references/EXAMPLE-php.md - php 示例项目代码
• references/EXAMPLE-ruby-on-rails.md - ruby-on-rails 示例项目代码
• references/EXAMPLE-ruby.md - ruby 示例项目代码
• references/EXAMPLE-android.md - android 示例项目代码
• references/EXAMPLE-swift.md - swift 示例项目代码
• references/EXAMPLE-react-native.md - react-native 示例项目代码
• references/EXAMPLE-expo.md - expo 示例项目代码
• references/next-js.md - Next.js
• references/react.md - React
• references/react-router-v6.md - React router v6
• references/react-router-v7-framework-mode.md - React router v7 框架模式（remix v3）
• references/react-router-v7-data-mode.md - React router v7 数据模式
• references/react-router-v7-declarative-mode.md - React router v7 声明式模式
• references/nuxt-js-3-6.md - Nuxt.js（v3.0 到 v3.6）
• references/nuxt-js.md - Nuxt.js
• references/vue-js.md - Vue.js
• references/tanstack-start.md - Tanstack start
• references/svelte.md - Svelte
• references/astro.md - Astro
• references/angular.md - Angular
• references/js.md - JavaScript 网页
• references/posthog-js.md - PostHog JavaScript 网页 SDK
• references/node.md - Node.js
• references/posthog-node.md - PostHog Node.js SDK
• references/django.md - Django
• references/flask.md - Flask
• references/python.md - Python
• references/posthog-python.md - PostHog Python SDK
• references/dotnet.md - .net
• references/elixir.md - Elixir
• references/go.md - Go
• references/laravel.md - Laravel
• references/php.md - Php
• references/ruby-on-rails.md - Ruby on rails
• references/ruby.md - Ruby
• references/android.md - Android
• references/ios.md - Ios
• references/usage.md - Ios SDK 用法
• references/configuration.md - Ios SDK 配置
• references/flutter.md - Flutter
• references/react-native.md - React native
• references/identify-users.md - 识别用户
• references/COMMANDMENTS.md - 集成必须遵循的框架特定规则 每个框架参考都包含特定于 SDK 的安装、初始化和使用模式。请找到与用户技术栈匹配的参考。

核心原则

• 环境变量：始终使用环境变量存储 PostHog 密钥。切勿将其硬编码。
• 最小改动：在现有集成旁添加 PostHog 代码。不要替换或重构现有代码。
• 遵循示例：实现应尽可能遵循示例项目的模式。
• 分析约定：将事件名称、属性名称和功能标志键视为分析约定的一部分。复用项目中已有的名称和模式。引入新名称时，应确保清晰、描述性强，并与现有约定保持一致。