Starlight文档框架接入Microsoft Clarity用户行为分析

1. 项目背景与核心价值

去年接手公司内部文档平台升级时，第一次接触到Starlight这个基于Astro的文档框架。它的轻量化设计和Markdown友好特性让我们团队眼前一亮，但很快发现一个痛点——缺乏用户行为分析能力。当产品经理问"哪些文档章节被频繁查阅？用户在搜索框输入了什么失败关键词？"时，我们只能摊手。

这就是为什么我要把Microsoft Clarity接入Starlight。作为微软推出的免费用户行为分析工具，Clarity能提供：

• 热图追踪（点击/滚动/注意力）
• 会话回放（真实操作录像）
• 死链检测
• 搜索词分析

这套组合拳完美补足了文档站点的运营盲区。更妙的是，Clarity的隐私合规设计（自动模糊敏感数据）让它特别适合企业内部系统。

2. 环境准备与技术选型

2.1 基础环境要求

确保你的Starlight项目满足：

• Astro v3.0+（验证命令：npm list astro）
• Node.js v18+
• 已注册Microsoft Clarity账户（免费版足够应对日均5万PV）

注意：Clarity目前对SPA的支持有限，而Starlight恰是MPA架构，这是技术栈兼容的关键前提

2.2 接入方案对比

我们选择直接注入方案，因为：

1. 文档站点不需要复杂的事件跟踪
2. 避免GTM带来的额外学习成本
3. 微软官方推荐的生产环境方案

3. 分步实施指南

3.1 获取Clarity跟踪ID

1. 登录[Clarity控制台]
2. 创建新项目 → 选择"Website"
3. 复制形如k123abc456的Project ID

实操技巧：建议项目命名包含环境标识（如docs-prod/docs-staging），方便后期过滤数据

3.2 修改Starlight配置

在astro.config.mjs中添加客户端脚本：

import { defineConfig } from 'astro/config'; import starlight from '@astrojs/starlight'; export default defineConfig({ integrations: [ starlight({ // 原有配置... head: [ { tag: 'script', attrs: { type: 'text/javascript', innerHTML: ` (function(c,l,a,r,i,t,y){ c[a]=c[a]||function(){(c[a].q=c[a].q||[]).push(arguments)}; t=l.createElement(r);t.async=1;t.src="https://www.clarity.ms/tag/"+i; y=l.getElementsByTagName(r)[0];y.parentNode.insertBefore(t,y); })(window, document, "clarity", "script", "YOUR_PROJECT_ID"); `.replace('YOUR_PROJECT_ID', import.meta.env.PUBLIC_CLARITY_ID) } } ] }) ] });

3.3 环境变量配置

1. 创建.env文件：

PUBLIC_CLARITY_ID=k123abc456

2. 更新astro.config.mjs中的import.meta.env检查逻辑

避坑提示：不要在前端直接暴露Project ID，应通过构建时环境变量注入

4. 高级配置与优化

4.1 屏蔽敏感操作

在Clarity控制台设置：

• 屏蔽含/admin路径的页面录制
• 模糊输入框内容（适用于搜索框）
• 排除内部IP地址

// 可在脚本中添加额外配置 clarity('set', 'excludeSelectors', ['[data-sensitive]']);

4.2 自定义事件跟踪

示例：跟踪文档评分按钮点击

<button onclick="clarity('event', 'doc_rating', { value: 5 })" >