<p>data-* 属性不能写在 <head> 中，HTML 规范禁止且浏览器直接忽略；必须挂载到 <html> 或 <body>，推荐 <html> 标签以确保稳定访问和避免丢失。</p>
data-* 属性不能写在 里，写了也无效
HTML 规范明确禁止在 <head> 中使用 data-* 自定义属性。浏览器解析时会直接忽略它们——既不会出现在 DOM 树中，document.head.dataset 读不到，getAttribute() 也取不到。哪怕你硬塞进去：<head data-env="staging">，控制台执行 document.head.getAttribute('data-env') 依然返回 null。
根本原因：HTML 解析器只允许 <head> 包含特定元信息标签（<title>、<meta>、<link> 等），data-* 不在其白名单内。它不是“不推荐”，而是语法层面不合法。
常见误用场景：
- 想用
data-test-env标记测试环境，却加在<head>上 → 实际运行时 JS 完全感知不到 - 服务端模板渲染时统一注入
data-user-id到<head>→ 前端埋点脚本初始化失败，上报 payload 缺失关键字段 - 自动化测试框架依赖该属性做环境判定，结果所有测试用例都 fallback 到默认配置
真正有效的替代位置只有 <html> 或 <body>
需要全局上下文信息（如环境、用户身份、AB 实验分组），必须挂载到可被 JS 稳定访问的顶层元素上。最稳妥的是 <html> 标签——它始终存在、解析最早、无动态替换风险。
立即学习“前端免费学习笔记（深入）”；
示例写法：
<html data-env="prod" data-user-id="u_789" data-ab-group="v2"> <head>...</head> <body>...</body> </html>
对应 JS 读取方式（安全、兼容、无需等待 DOM 加载）：
将 Markdown 文章转换为微信公众号兼容的纯 HTML 格式。当用户要求"转成微信格式"、"生成公众号文章 HTML"、"排版到微信草稿箱"、"微信粘贴格式"时触发。输出带内联样式的纯 HTML，微信编辑器可直接渲染，无需额外适配。支持标题、段落、列表、粗体、行内代码、表格、引用块、代码块、配图的完整转换。
-
document.documentElement.dataset.env→"prod" -
document.documentElement.dataset.userId→"u_789" -
document.documentElement.dataset.abGroup→"v2"
注意：document.body 虽然也可用，但存在隐患——某些 SPA 框架或 SSR 渲染逻辑会替换整个 <body> 内容，导致挂载在其上的 data-* 丢失；而 <html> 是整个文档根节点，不会被重写。
自动化测试中读取 data-* 的典型陷阱
Playwright / Cypress / Selenium 等工具能直接读取 DOM 属性，但容易踩三个坑：
- 用
getAttribute('data-env')读<html>时，返回值是字符串，但测试断言常写成expect(env).toBe(true)→ 实际是"prod"，类型错配直接失败 - 在
beforeEach钩子中缓存document.documentElement.dataset，后续页面跳转后该对象未更新 → 仍用旧值做断言，掩盖真实环境切换问题 - 依赖
data-test-id定位元素，却把该属性写在动态生成的子组件内部（如 ReactuseEffect插入的按钮），而测试脚本执行时该节点尚未挂载 → 查找不到元素
正确做法：在测试启动阶段（如 Cypress 的 support/e2e.js）通过 cy.document().then(doc => doc.documentElement.dataset) 显式提取，并作为 fixture 注入各测试用例；对动态元素，改用 cy.get('[data-test-id="submit-btn"]', { timeout: 10000 }) 加超时兜底。
埋点 SDK 初始化时 data-* 的加载时机很关键
埋点 SDK（如自研 trackSDK 或神策/友盟）通常在 <head> 中同步加载，但它依赖的上下文数据（如 data-user-id）如果还没被 JS 读到，就会发空字段或 fallback 默认值。
解决方案只有两个：
- 把 SDK 初始化逻辑延迟到
DOMContentLoaded之后，确保document.documentElement.dataset已就绪 - 更推荐：服务端直出时，将关键
data-*值内联进 SDK 初始化脚本，例如：<script> window.TRACK_CONFIG = { env: '<code>prod</code>', userId: '<code>u_789</code>', abGroup: '<code>v2</code>' }; // 然后加载 trackSDK.min.js </script>这样绕过 DOM 读取，彻底规避竞态
切记：不要在 <head> 里写 <script>trackSDK.init({ userId: document.documentElement.dataset.userId })</script> —— 此时 document.documentElement 已存在，但其 dataset 是空对象，因为浏览器还没解析完 HTML 标签属性。
