integration-javascript_node

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

PostHog integration for JavaScript Node

PostHog集成指南（Node.js JavaScript版）

This skill helps you add PostHog analytics to JavaScript Node applications.

本指南将帮助你为JavaScript Node.js应用添加PostHog分析功能。

Workflow

实施步骤

Follow these steps in order to complete the integration:

```
basic-integration-1.0-begin.md
```
- PostHog Setup - Begin ← Start here
```
basic-integration-1.1-edit.md
```
- PostHog Setup - Edit
```
basic-integration-1.2-revise.md
```
- PostHog Setup - Revise
```
basic-integration-1.3-conclude.md
```
- PostHog Setup - Conclusion

请按以下顺序完成集成：

```
basic-integration-1.0-begin.md
```
- PostHog配置 - 开始 ← 从此处开始
```
basic-integration-1.1-edit.md
```
- PostHog配置 - 编辑
```
basic-integration-1.2-revise.md
```
- PostHog配置 - 修订
```
basic-integration-1.3-conclude.md
```
- PostHog配置 - 完成

Reference files

参考文件

```
references/node.md
```
- Node.js - docs
```
references/posthog-node.md
```
- PostHog Node.js SDK
```
references/identify-users.md
```
- Identify users - docs

references/basic-integration-1.0-begin.md

- PostHog setup - begin

references/basic-integration-1.1-edit.md

- PostHog setup - edit

references/basic-integration-1.2-revise.md

- PostHog setup - revise

references/basic-integration-1.3-conclude.md

- PostHog setup - conclusion

The example project shows the target implementation pattern. Consult the documentation for API details.

```
references/node.md
```
- Node.js - 官方文档
```
references/posthog-node.md
```
- PostHog Node.js SDK
```
references/identify-users.md
```
- 用户身份识别 - 官方文档

references/basic-integration-1.0-begin.md

- PostHog配置 - 开始

references/basic-integration-1.1-edit.md

- PostHog配置 - 编辑

references/basic-integration-1.2-revise.md

- PostHog配置 - 修订

references/basic-integration-1.3-conclude.md

- PostHog配置 - 完成

示例项目展示了目标实现模式。如需了解API细节，请查阅官方文档。

Key principles

核心原则

Environment variables: Always use environment variables for PostHog keys. Never hardcode them.
Minimal changes: Add PostHog code alongside existing integrations. Don't replace or restructure existing code.
Match the example: Your implementation should follow the example project's patterns as closely as possible.

环境变量：始终使用环境变量存储PostHog密钥，切勿硬编码。
最小化改动：在现有集成代码旁添加PostHog相关代码，不要替换或重构现有代码。
匹配示例：你的实现应尽可能贴合示例项目的模式。

Framework guidelines

框架指南

posthog-node is the Node.js server-side SDK package name – do NOT use posthog-js on the server
Include enableExceptionAutocapture: true in the PostHog constructor options
Add posthog.capture() calls in route handlers for meaningful user actions – every route that creates, updates, or deletes data should track an event with contextual properties
Add posthog.captureException(err, distinctId) in the application's error handler (e.g., Express error middleware, Fastify setErrorHandler, Koa app.on('error'))
In long-running servers, the SDK batches events automatically – do NOT set flushAt or flushInterval unless you have a specific reason to
For short-lived processes (scripts, CLIs, serverless), set flushAt to 1 and flushInterval to 0 to send events immediately
Reverse proxy is NOT needed for server-side Node.js – only client-side JavaScript needs a proxy to avoid ad blockers
Remember that source code is available in the node_modules directory
Check package.json for type checking or build scripts to validate changes

posthog-node是Node.js服务端SDK的包名——请勿在服务端使用posthog-js
在PostHog构造函数的配置项中设置
```
enableExceptionAutocapture: true
```
在路由处理器中为有意义的用户操作添加
```
posthog.capture()
```
调用——所有涉及数据创建、更新或删除的路由，都应追踪带有上下文属性的事件
在应用的错误处理器中添加
```
posthog.captureException(err, distinctId)
```
（例如Express错误中间件、Fastify的setErrorHandler、Koa的app.on('error')）
对于长期运行的服务端，SDK会自动批量处理事件——除非有特殊需求，否则不要设置
```
flushAt
```
或
```
flushInterval
```
对于短期运行的进程（脚本、CLI、无服务器函数），设置
```
flushAt: 1
```
和
```
flushInterval: 0
```
以立即发送事件
服务端Node.js无需反向代理——仅客户端JavaScript需要通过代理规避广告拦截器
注意：SDK源代码可在
```
node_modules
```
目录中找到
可查看
```
package.json
```
中的类型检查或构建脚本，以验证你的改动是否合规

Identifying users

用户身份识别

Identify users during login and signup events. Refer to the example code and documentation for the correct identify pattern for this framework. If both frontend and backend code exist, pass the client-side session and distinct ID using

X-POSTHOG-DISTINCT-ID

and

X-POSTHOG-SESSION-ID

headers to maintain correlation.

在用户登录和注册事件中完成用户身份识别。请参考示例代码和官方文档，了解适用于该框架的正确身份识别模式。如果同时存在前端和后端代码，请通过

X-POSTHOG-DISTINCT-ID

和

X-POSTHOG-SESSION-ID

请求头传递客户端会话和唯一ID，以保持前后端数据的关联性。

Error tracking

错误追踪

Add PostHog error tracking to relevant files, particularly around critical user flows and API boundaries.

在相关文件中添加PostHog错误追踪功能，重点覆盖关键用户流程和API边界。