mcpField
I
integration-astro-hybrid

integration-astro-hybrid

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

关于 integration-astro-hybrid

用于在 Astro (Hybrid) 应用中集成 PostHog 分析的技能，按阶段提供客户端与服务端跟踪、用户识别和错误跟踪指南。

主要功能

  1. 01四阶段集成流程
  2. 02Astro 专属配置指南
  3. 03客户端与服务端事件跟踪
  4. 04预渲染与 SSR 指南
  5. 05用户识别建议
  6. 06错误跟踪建议

适用场景

  1. 01为 Astro Hybrid 应用添加 PostHog
  2. 02在 API 路由中跟踪事件
  3. 03在登录和注册时识别用户

安装

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

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

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

包含的文件

除 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（Hybrid）的 PostHog 集成

此技能可帮助你在 Astro（Hybrid）应用中添加 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（Hybrid）示例项目代码
  • 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 组件，并使用该布局包裹所有页面
  • 在 src/pages/api/ 下的 API 路由中使用 posthog-node 跟踪服务端事件
  • 使用单例模式存储 posthog-node 客户端实例（src/lib/posthog-server.ts），避免创建多个客户端
  • 在 Astro 5 中，使用带适配器的 output static（默认值）；页面默认会预渲染
  • 对需要服务端渲染的特定页面，使用 export const prerender = false 以启用 SSR
  • 仅需要服务端 PostHog 跟踪的页面（例如由 API 支持的表单）才应关闭预渲染

识别用户

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

错误跟踪

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

评论

支持 Markdown