data-track命名必须全局唯一且不可动态拼接，否则数仓解析报错10023；须用小写+连字符、层级≤3级、提前录入白名单并CI校验；data-track-params必须为合法JSON字符串，提取时加try/catch；监听必须用pointerdown+closest('[data-track]')，敏感字段严禁明文出现在任何data-*属性中。
data-track 属性命名必须全局唯一且不可动态拼接
上线后改名等于埋点字段失效，数仓解析会直接报错 10023。命名不是“写得顺口就行”，而是要和业务事件字典对齐：
- 用小写字母 + 连字符，比如
data-track="page_view"、data-track="item_click" - 禁止在 JS 里拼接字符串赋值：
el.setAttribute('data-track', 'btn_' + type)—— 这会让埋点 SDK 无法静态识别 - 多级上下文用下划线分隔，但层级不超过 3 级：
data-track="search_suggestion_submit"，别写成data-track="search_suggestion_list_item_submit" - 所有
data-track值必须提前录入埋点平台白名单，CI 构建时做校验
data-track-params 必须是合法 JSON 字符串，不能是对象字面量
属性值不是 JS 代码，浏览器不会执行它。很多团队在这里栽跟头：
- ✅ 正确：
data-track-params='{"tab":"recommend","position":2}'（单引号包裹，双引号在内） - ❌ 错误：
data-track-params="{tab: 'recommend'}"（没引号、单引号、冒号无引号 → 解析失败） - ❌ 错误：
data-track-params={"tab":"recommend"}（没引号 → HTML 解析器直接截断） - JS 提取时必须加
try/catch：JSON.parse(el.getAttribute('data-track-params') || '{}')
监听层必须用 closest()，不能依赖 event.target 直接命中
用户点的是图标、文字或 padding 区域，event.target 很可能不是你写 data-track 的那个容器。
- 错误写法：
document.addEventListener('click', e => { const el = e.target; console.log(el.dataset.track); }) - 正确写法：
document.addEventListener('pointerdown', e => { const el = e.target.closest('[data-track]'); if (el) { /* 提取上报 */ } }) - 优先用
pointerdown而非click，避免 iOS Safari 300ms 延迟导致跳转丢失 -
closest()在 IE11 需要 polyfill，但微前端场景下更常见的是子应用覆盖原生事件，此时需确认是否已禁用 v-click-track 类指令
敏感字段绝对不能出现在任何 data-* 属性中
HTML 源码、DevTools、网络面板、CDN 缓存、爬虫快照……全都能看到。这不是“理论上不安全”，而是“已经明文暴露”。
立即学习“前端免费学习笔记（深入）”；
- 禁止出现：
data-user-id="123456"、data-phone="138****1234"、data-token="abc123" - 正确做法：只放无意义标识，如
data-user-hash="a7f2e"，后端通过该哈希查真实 ID - SSR 渲染时尤其危险——服务端模板里插
data-属性，等于把脱敏前数据吐给客户端源码 - CI 流程中应加入正则扫描：
/data-(user|phone|token|id|email)/i，命中即阻断发布
真正难的不是写对一个 data-track，而是让成千上万个分散在不同组件、不同仓库、不同技术栈里的自定义属性，在三年后仍能被同一套 SDK 准确提取、不丢不乱、不暴露隐私。这靠的不是命名灵感，而是约束力和自动化检查。
