<p>data-* 属性是唯一合规可靠的初始化参数载体，应挂载于<html>或<body>标签，用小写字母和短横线命名，结构化数据需JSON序列化，敏感信息严禁传递。</p>
data-* 属性是唯一合规且可靠的初始化参数载体
HTML 标准明确允许通过 data-* 属性在元素上附加自定义数据，浏览器会原样保留、不解析、不执行，且可通过 dataset API 安全读取。其他方式（如直接写 config='{"api":"/v1"}'）属于非法属性，可能被浏览器忽略或触发解析异常，尤其在严格模式或 CSP 环境下更不可靠。
常见错误现象：配置字符串被 HTML 解析器截断（如含 & 或 "）、JSON 被当成普通文本未转义导致 JS 解析失败、服务端模板渲染时未做 HTML 实体转义引发 XSS 风险。
- 必须使用小写字母和短横线命名，如
data-api-base，对应 JS 中的element.dataset.apiBase - 值应为纯字符串；若需传递结构化数据（如对象/数组），先用
JSON.stringify()序列化，再在 JS 中JSON.parse()还原 - 避免在
<script>标签内硬编码配置——这会破坏 SSR 可复用性，也难做服务端差异化注入
推荐挂载位置：<html> 或 <body> 标签上
把初始化配置放在 <html data-api-base="/api" data-env="prod"> 或 <body data-config='{"timeout":5000}'> 最合理。这样全局可访问，无需依赖 DOM 就绪，也避免因组件挂载顺序导致读取不到的问题。
不要放在某个业务组件的容器上（如 <div id="app" data-user-id="123">），除非该配置**仅限该组件使用**；否则容易造成耦合、重复定义或读取时机错乱。
立即学习“前端免费学习笔记（深入）”；
文章转信息图。将文章/笔记转化为手机可读的 HTML 信息图，自动匹配视觉风格。触发场景：文章转图、笔记转图、信息图、转小红书图、做张图、可视化这篇文章、文生图。
-
<html>是最优先选择：它在 DOM 构建最早阶段就存在，document.documentElement.dataset可在任何脚本中立即访问 - 如果配置含敏感信息（如密钥），切勿通过
data-*传递——这类信息应由后端接口动态返回，并配合鉴权控制 - 服务端模板（如 EJS、Jinja2）中输出时，务必对 JSON 值做 HTML 实体转义，例如：
data-config=""
JavaScript 中安全读取并解析的典型写法
直接读 dataset 得到的是字符串，不能假设它已自动解析为对象。常见错误是写 const cfg = document.body.dataset.config.timeout，结果报 Cannot read property 'timeout' of undefined —— 因为 dataset.config 是字符串，不是对象。
const configEl = document.documentElement;
const rawConfig = configEl.dataset.config;
<p>let appConfig = {};
try {
appConfig = rawConfig ? JSON.parse(rawConfig) : {};
} catch (e) {
console.error('Failed to parse data-config:', e);
// 降级处理，如使用默认值
appConfig = { timeout: 3000 };
}</p><p>// 同时兼容单个字段（如 data-api-base）和整块 JSON（data-config）
const apiBase = configEl.dataset.apiBase || appConfig.apiBase || '/api';</p>- 始终用
try/catch包裹JSON.parse()，前端无法控制服务端输出是否合法 - 不要混合使用：要么全用独立
data-xxx字段（适合少量扁平配置），要么统一走data-config（适合嵌套结构），避免维护混乱 - 注意 IE11 不支持
dataset，需用getAttribute('data-config')兜底（如项目还需兼容）
与现代构建工具（Vite / Webpack）共存时的注意事项
构建工具常注入运行时环境变量（如 import.meta.env.VUE_APP_API），但这和 HTML 中的 data-* 是两套机制：前者在构建时替换，后者在运行时注入。二者不冲突，但用途不同——data-* 更适合服务端动态决定的值（如用户所属租户、A/B 测试分组、CDN 域名）。
容易踩的坑是：在 Vite 的 index.html 中写 <div id="app" data-env="<code>%ENV%">，指望构建时替换——这不会生效，因为 Vite 默认不处理 index.html 中的模板语法（除非显式启用 html-plugin 或用 <%= ... %> 配合预处理器）。
- 若需构建时注入，改用 Vite 的
transformIndexHtml钩子或 Webpack 的HtmlWebpackPlugin插件动态插入data-* - 若需运行时注入（如 SSR 或边缘函数生成页面），确保后端输出的 HTML 中
data-*值已正确序列化和转义 - 不要在 Vue/React 组件的
mounted或useEffect中才去读配置——应提前在入口 JS（如main.ts）里完成解析并传入应用实例
配置真正生效的关键，不在“怎么写”，而在于“谁在什么时候写、谁在什么时候读”。漏掉服务端转义、跳过 JSON 解析异常处理、或把运行时配置混进构建时流程，都会让看似简单的 data-* 变成线上故障的隐性源头。
