1. 项目背景与核心价值去年接手公司内部文档平台升级时第一次接触到Starlight这个基于Astro的文档框架。它的轻量化设计和Markdown友好特性让我们团队眼前一亮但很快发现一个痛点——缺乏用户行为分析能力。当产品经理问哪些文档章节被频繁查阅用户在搜索框输入了什么失败关键词时我们只能摊手。这就是为什么我要把Microsoft Clarity接入Starlight。作为微软推出的免费用户行为分析工具Clarity能提供热图追踪点击/滚动/注意力会话回放真实操作录像死链检测搜索词分析这套组合拳完美补足了文档站点的运营盲区。更妙的是Clarity的隐私合规设计自动模糊敏感数据让它特别适合企业内部系统。2. 环境准备与技术选型2.1 基础环境要求确保你的Starlight项目满足Astro v3.0验证命令npm list astroNode.js v18已注册Microsoft Clarity账户免费版足够应对日均5万PV注意Clarity目前对SPA的支持有限而Starlight恰是MPA架构这是技术栈兼容的关键前提2.2 接入方案对比方案实现复杂度数据延迟功能完整性直接注入脚本★☆☆☆☆1分钟100%Google Tag Manager★★☆☆☆5-10分钟90%Segment等第三方中转★★★★☆15分钟80%我们选择直接注入方案因为文档站点不需要复杂的事件跟踪避免GTM带来的额外学习成本微软官方推荐的生产环境方案3. 分步实施指南3.1 获取Clarity跟踪ID登录[Clarity控制台]创建新项目 → 选择Website复制形如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].qc[a].q||[]).push(arguments)}; tl.createElement(r);t.async1;t.srchttps://www.clarity.ms/tag/i; yl.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 环境变量配置创建.env文件PUBLIC_CLARITY_IDk123abc456更新astro.config.mjs中的import.meta.env检查逻辑避坑提示不要在前端直接暴露Project ID应通过构建时环境变量注入4. 高级配置与优化4.1 屏蔽敏感操作在Clarity控制台设置屏蔽含/admin路径的页面录制模糊输入框内容适用于搜索框排除内部IP地址// 可在脚本中添加额外配置 clarity(set, excludeSelectors, [[data-sensitive]]);4.2 自定义事件跟踪示例跟踪文档评分按钮点击button onclickclarity(event, doc_rating, { value: 5 }) >