从数据洞察到用户增长：HagiCode 博客接入 Clarity Analytics 的完整指南

本文将分享如何在 Starlight 文档站点中优雅地接入 Microsoft Clarity，不仅能看清用户行为，还能确保隐私合规。这套方案是我们在 HagiCode 项目中实践总结出来的，希望能给同样在折腾数据统计的你一点参考。

背景：为什么我们需要 Clarity？

以下代码展示了如何在 Astro 集成中根据环境变量动态注入 Microsoft Clarity 脚本，仅在生效时进行生产环境加载。

105 | interface Props {
106 |   // 未来可扩展: 允许手动覆盖 Project ID
107 |   projectId?: string;
108 | }
109 | 
110 | const {
111 |   projectId = import.meta.env.CLARITY_PROJECT_ID,
112 | } = Astro.props;
113 | 
114 | const isProduction = import.meta.env.PROD;
115 | ---
116 | 
117 | {isProduction && projectId && (
118 |   
)}

关键点解析：

is:inline：告诉 Astro 不要处理这个 script 标签内的内容，直接输出到 HTML。这对第三方统计脚本至关重要，否则 Astro 的打包优化可能会导致脚本失效。
define:vars：这是 Astro 3+ 的特性，允许在作用域内安全地注入变量。
import.meta.env.PROD：确保在本地开发时（除非为了调试）不产生无效统计，保持数据纯净。

仅仅加上代码是不够的，特别是在 GDPR 管辖区域。我们需要尊重用户的选择。

HagiCode 的做法是提供一个简单的开关。虽然这不是全功能的 Cookie Banner，但对于纯展示的技术文档站点来说，通常属于"必要"或"统计"类 Cookie，可以通过隐私声明告知并默认开启，或者在 Footer 链接到隐私设置页面。

如果需要更严谨的控制，你可以结合 localStorage 来记录用户的选择：

本文将介绍用于主题切换与持久化的 TypeScript 工具函数，通过类型安全与环境检测实现严谨控制。

367 | export function getInitialTheme(): Theme;
368 | export function getSystemTheme(): Theme;
369 | export function setTheme(theme: Theme): void;
370 | export function applyTheme(theme: Theme): void;
371 | ```
372 | 
373 | **设计原则**：
374 | - **纯函数**：无副作用（除了 `setTheme` 和 `applyTheme`）
375 | - **类型安全**：完整的 TypeScript 类型推导
376 | - **环境检测**：SSR 安全（`typeof window` 检查）
377 | - **单一职责**：每个函数只做一件事
378 | 
379 | **关键实现**：
380 | ```typescript
381 | export function getInitialTheme(): Theme {
382 |   if (typeof window === 'undefined') return 'dark';
383 | 
384 |   const stored = localStorage.getItem(THEME_KEY);
385 |   if (stored === 'light' || stored === 'dark') return stored;
386 |

文件：openspec/changes/archive/2026-01-29-theme-toggle-implementation/design.md

// 简单示例：检查用户是否拒绝统计
const consent = localStorage.getItem('clarity_consent');
if (consent !== 'denied') {
    // 执行上面的 Clarity 初始化代码
    window.clarity('start', clarityId);
}

经验总结与坑点

在将这套方案落地到 HagiCode 的过程中，我们总结了几个容易被忽视的细节：

StarlightWrapper.astro 是个陷阱：
如前所述，不要试图去创建一个全局 Wrapper 来注入脚本，这在 Starlight 中行不通。老老实实覆盖特定组件（如 StarlightFooter.astro 或 StarlightHead.astro）才是正解。
脚本位置的性能考量：
虽然 Clarity 建议放在中以确保数据准确性，但对于文档站点，首屏加载速度（LCP）直接影响了 SEO 和用户留存。我们选择了放在 Footer（Body 底部），这会轻微丢失极少量"秒退"用户的数据，但换来了更快的页面加载体验，这是一个值得的权衡。
开发环境的干扰：
一定要加上 import.meta.env.PROD 判断。在开发模式下，你会频繁刷新页面，这会产生大量无意义的测试数据，污染你的 Clarity 仪表盘。

效果验证

部署完成后，你可以在 Clarity 控制台查看实时数据。通常在几分钟内，你就能看到用户的heatmap（热力图）和 recordings（录屏）。

对于 HagiCode 来说，通过这些数据我们发现：

很多用户会反复查看"快速开始"章节，说明我们的安装指引可能还不够直观。
"API 参考"页面的停留时间最长，证实了我们核心用户群体的需求。

总结

接入 Microsoft Clarity 并不需要复杂的服务端改造，也不需要引入沉重的 SDK。

利用 Starlight 的组件覆盖机制，我们仅通过一个轻量级的 StarlightFooter.astro 组件，就实现了全局数据统计。这种"微集成"的方式，既保证了代码的整洁，又赋予了我们洞察用户行为的能力。

如果你也在运营技术类项目，特别是像 HagiCode 这样需要不断迭代文档的项目，强烈建议尝试接入 Clarity。数据会告诉你，用户真正的痛点在哪里。

参考资料

感谢您的阅读,如果您觉得本文有用,快点击下方点赞按钮👍,让更多的人看到本文。

本内容采用人工智能辅助协作,经本人审核,符合本人观点与立场。

本文作者: newbe36524
本文链接: https://hagicode-org.github.io/site/blog/2026-02-04-starlight-docs-integration-microsoft-clarity/
版权声明: 本博客所有文章除特别声明外,均采用 BY-NC-SA 许可协议。转载请注明出处!

基于 Starlight 文档站点接入 Microsoft Clarity 的完整实践指南

从数据洞察到用户增长：HagiCode 博客接入 Clarity Analytics 的完整指南

背景：为什么我们需要 Clarity？

进阶：隐私合规与 Cookie 控制

经验总结与坑点

效果验证

总结

参考资料