data-*属性是HTML中唯一合法且零依赖的全局配置挂载方式，需挂载在JS可稳定访问的根节点上，保持字符串化，Shadow DOM组件须显式桥接读取，且不具持久性。
HTML 本身不提供“组件配置注入”的原语，所谓全局配置，本质是把配置值挂载到 DOM 节点上，再由 JS 或 CSS 按需读取。关键不是“怎么写 HTML”，而是“在哪挂、怎么读、怎么避免踩坑”。
data-* 属性是唯一合法且零依赖的挂载方式
浏览器标准只允许在元素上使用 data-* 属性传递自定义配置，它不干扰语义、不触发重排、可被 JS 直接读取：
-
data-api-endpoint、data-theme、data-timeout这类命名是安全的；data-config这种模糊名容易冲突，别用 - 必须挂载在 JS 能稳定访问的根节点上，比如
<div id="app" data-theme="dark" data-api="/api/v1"></div>；别塞进<body>或临时容器里，否则 JS 初始化时可能拿不到 - 值尽量保持字符串化，避免 JSON 字符串嵌套（如
data-config='{"a":1}'），JS 解析易出错；复杂结构优先走localStorage或服务端渲染
:root CSS 变量不能替代 data-* 做运行时配置
:root 里的 --api-url 或 --timeout-ms 看似方便，但它是静态声明，无法响应页面加载后的动态变更：
- 构建时硬编码进 CSS 文件？部署就得改 CSS，不可行
- JS 用
document.documentElement.style.setProperty()动态写入？会覆盖其他内联样式（比如框架注入的动画变量），引发意外副作用 - CSS 变量只能被
var()引用，无法被 JS 直接序列化或条件判断——你没法写if (getComputedStyle(document.documentElement).getPropertyValue('--env') === 'prod')这种逻辑
Shadow DOM 组件必须从宿主节点读取 data-*
如果你的组件用了 Shadow DOM（比如 <my-card>），它内部无法直接访问外部 data-*，必须显式桥接：
立即学习“前端免费学习笔记（深入）”；
- 在组件初始化时，从挂载点（如
document.getElementById('widget-root')）读取dataset，再传入 shadowRoot - 不要在 Shadow DOM 内部再写一遍
data-*——那只是副本，和宿主不同步 - 若需响应式更新（如主题切换），监听宿主节点的
DOMSubtreeModified不可靠；推荐用MutationObserver观察dataset变更，或干脆让宿主主动调用组件方法更新
真正容易被忽略的是：data-* 属性只在当前页面生命周期内有效，刷新即丢。如果配置需要跨页面保留，必须搭配 localStorage 或 URL 参数同步——HTML 标签本身不负责持久化。
