mcpField
I
integration-astro-ssr

integration-astro-ssr

github.com/posthog数据与数据库76108 次安装今天更新
代码仓库

关于 integration-astro-ssr

用于为 Astro 服务端渲染应用添加 PostHog 分析的技能，提供分步集成流程，并说明客户端与服务端跟踪、身份识别和错误处理。

主要功能

  1. 01按四步集成流程完成设置
  2. 02使用环境变量存放 PostHog 密钥
  3. 03通过 Astro 组件初始化客户端跟踪
  4. 04使用 posthog-node 跟踪服务端事件
  5. 05关联客户端与服务端会话
  6. 06为关键流程添加错误跟踪

适用场景

  1. 01在 Astro SSR 应用中集成 PostHog 分析
  2. 02从 Astro API 路由跟踪事件
  3. 03维持客户端与服务端的会话关联

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/posthog/skills --skill integration-astro-ssr

安装后在 Claude Code 中输入/integration-astro-ssr确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/
astro.md
basic-integration-1.0-begin.md
basic-integration-1.1-edit.md
basic-integration-1.2-revise.md
basic-integration-1.3-conclude.md
EXAMPLE.md
identify-users.md

详细介绍

Astro（SSR）的 PostHog 集成

此技能可帮助你为 Astro（SSR）应用添加 PostHog 分析。

工作流

请按顺序完成以下步骤：

  1. basic-integration-1.0-begin.md - PostHog 设置 - 开始 ← 从这里开始
  2. basic-integration-1.1-edit.md - PostHog 设置 - 编辑
  3. basic-integration-1.2-revise.md - PostHog 设置 - 修订
  4. basic-integration-1.3-conclude.md - PostHog 设置 - 结束

参考文件

  • references/EXAMPLE.md - Astro（SSR）示例项目代码
  • references/astro.md - Astro - 文档
  • 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 详情请参阅文档。

核心原则

  • 环境变量：始终使用环境变量存储 PostHog 密钥。切勿将其硬编码。
  • 尽量少改动：在现有集成旁添加 PostHog 代码。不要替换或重构现有代码。
  • 遵循示例：实现应尽可能贴合示例项目中的模式。

框架指南

  • 始终在 PostHog 脚本标签上使用 is:inline 指令，以防 Astro 处理脚本并导致 TypeScript 错误
  • 在 Astro 中，客户端环境变量使用 PUBLIC_ 前缀（例如，PUBLIC_POSTHOG_PROJECT_TOKEN）
  • 在 src/components/ 中创建 posthog.astro 组件，以便在多个页面中重复使用初始化逻辑
  • 在 Layout 中导入 PostHog 组件，并使用该 Layout 包裹所有页面
  • 在 src/pages/api/ 下的 API 路由中使用 posthog-node 进行服务端事件追踪
  • 使用单例模式存储 posthog-node 客户端实例（src/lib/posthog-server.ts），避免创建多个客户端
  • 通过 X-PostHog-Session-Id 请求头将客户端会话 ID 传递给服务端，以实现统一的会话追踪

识别用户

在登录和注册事件期间识别用户。请参阅示例代码和文档，了解适用于此框架的正确识别模式。如果前端和后端代码都存在，请使用 X-POSTHOG-DISTINCT-ID 和 X-POSTHOG-SESSION-ID 请求头传递客户端会话 ID 和 distinct ID，以保持关联。

错误追踪

在相关文件中添加 PostHog 错误追踪，尤其是在关键用户流程和 API 边界附近。

评论

支持 Markdown