installing-posthog-in-a-codebase

在代码库中安装 PostHog

当你能够读取和编辑用户的代码时，使用此技能。 如果你无法访问他们的代码（这在网页版 ChatGPT 或网页版 Claude 中很常见），请使用 installing-posthog-from-chat。

PostHog 的文档是各 SDK 设置的权威来源。 初始化选项、文件位置和推荐设置会随 SDK 版本变化，因此编写代码前，请先阅读对应框架的文档页面，并以文档为准，而不是依赖记忆。

1. 查找框架并阅读其文档

根据清单文件（package.json、pyproject.toml、requirements.txt、Gemfile、composer.json、go.mod 等）和应用的入口点，检测所用框架。 具有自有后端的 Web 应用通常需要客户端 SDK 和服务端 SDK，因此请阅读这两者的文档页面。

框架	文档页面
JavaScript Web（任意框架）	https://posthog.com/docs/libraries/js.md
React，包括 Vite 应用	https://posthog.com/docs/libraries/react.md
Next.js	https://posthog.com/docs/libraries/next-js.md
Vue.js	https://posthog.com/docs/libraries/vue-js.md
Nuxt	https://posthog.com/docs/libraries/nuxt-js.md
Svelte 和 SvelteKit	https://posthog.com/docs/libraries/svelte.md
Angular	https://posthog.com/docs/libraries/angular.md
Astro	https://posthog.com/docs/libraries/astro.md
Remix	https://posthog.com/docs/libraries/remix.md
React Router	https://posthog.com/docs/libraries/react-router.md
TanStack Start	https://posthog.com/docs/libraries/tanstack-start.md
Node.js，包括 Express	https://posthog.com/docs/libraries/node.md
Python，包括 FastAPI	https://posthog.com/docs/libraries/python.md
Django	https://posthog.com/docs/libraries/django.md
Flask	https://posthog.com/docs/libraries/flask.md
Ruby	https://posthog.com/docs/libraries/ruby.md
Ruby on Rails	https://posthog.com/docs/libraries/ruby-on-rails.md
PHP	https://posthog.com/docs/libraries/php.md
Laravel	https://posthog.com/docs/libraries/laravel.md
Go	https://posthog.com/docs/libraries/go.md
Java	https://posthog.com/docs/libraries/java.md
.NET	https://posthog.com/docs/libraries/dotnet.md
Elixir	https://posthog.com/docs/libraries/elixir.md
Rust	https://posthog.com/docs/libraries/rust.md
React Native	https://posthog.com/docs/libraries/react-native.md
Flutter	https://posthog.com/docs/libraries/flutter.md
iOS	https://posthog.com/docs/libraries/ios.md
Android	https://posthog.com/docs/libraries/android.md

对于未列出的框架，请使用框架名称调用 docs-search。

2. 安装最新 SDK

使用项目自己的包管理器添加各个软件包，且不要指定版本，例如 npm install posthog-js、pnpm add posthog-node、uv add posthog 或 bundle add posthog-ruby。 这样会解析到最新版本。 不要凭记忆在清单文件中填写版本号，以免固定到旧版本。

在 monorepo 中，应将软件包安装到运行应用的包中，而不是工作区根目录。

3. 获取令牌和主机

不带 ID 调用 project-get。 将 api_token 用作项目令牌，将 api_host 用作 SDK 的 host 选项。

• 在代码中从环境变量读取这两个值，使用文档页面中的变量名（例如 NEXT_PUBLIC_POSTHOG_PROJECT_TOKEN 和 NEXT_PUBLIC_POSTHOG_HOST）。
• 将实际值写入框架加载的环境文件，例如 .env.local 或 .env。如果项目有示例环境文件，请在其中添加变量名，并将值留空。
• 切勿在源文件中硬编码令牌或主机，也不要在代码中将它们用作回退默认值。

4. 按文档所示进行初始化

• 在文档页面指定的位置初始化 SDK 一次。不要在其他位置再次初始化。
• 对于 posthog-js，将 defaults 设置为文档页面所示的日期。它会选择最新的一组推荐设置，因此不要凭记忆填写日期。
• 对于长时间运行的服务器中的后端 SDK，每个进程创建一个客户端，重复使用，并在进程退出时关闭。不要为每个请求创建客户端。
• 在无服务器或边缘处理程序中（例如 Vercel 上的 Next.js 路由处理程序或 AWS Lambda），运行时可能会在响应发送后立即冻结，导致排队的事件丢失。在处理程序返回前刷新：对重复使用的客户端调用 await flush()，或按文档页面所述使用平台的 waitUntil。
• 对于服务端渲染应用（Django、Rails、Laravel 等），除了浏览器代码片段外，还要添加服务端 SDK。

5. 识别用户

如果应用支持登录，请在登录后调用 identify，并使用身份验证系统中的稳定用户 ID（例如数据库 ID），而不是电子邮件地址或显示名称。 退出登录时调用 reset()。 发送服务端事件时使用相同的 distinct ID，让客户端和服务端事件关联到同一个人。

6. 验证

运行项目的构建、类型检查或测试，并修复此次更改导致的问题。 如果可以运行应用，请加载一个页面，并使用 read-data-schema 或 execute-sql 检查事件是否已到达。 告知用户部署前需要在托管服务提供商处添加哪些环境变量。