在单页应用（SPA）中，静态 HTML 入口文件看着简单，但稍不留神就会踩坑。比如 DOCTYPE 和 lang 必须顶格写，否则浏览器直接进怪异模式；meta charset 必须是 head 的第一个标签；title 不能缺失；挂载容器必须为空、唯一且带 id；静态资源要使用相对路径；第三方库最好硬写在 index.html 里——这些细节哪一个出问题，首屏就可能白屏或乱码。下面逐条拆解，顺便给一些实操建议。

DOCTYPE 和 lang 属性必须顶格写，否则直接进怪异模式

浏览器一读到非空白字符就决定渲染模式。哪怕开头是 BOM（EF BB BF）、空格或注释，IE 和微信 WebView 就会强制触发 Quirks Mode——box-sizing 失效、position: sticky 不工作、getBoundingClientRect() 返回异常值。

实操建议：

• 用 VS Code 打开文件，右下角确认编码为 UTF-8（不是 UTF-8 with BOM）
• 终端运行 hexdump -C index.html | head -n 1，前三个字节必须是 3c 21 44（即 ）
• 不能写成 lang="zh"、lang="cn" 或 lang="zh_CN"；BCP 47 要求连字符 + 地区码大写
• 局部英文内容用

  API response

  ，别依赖 JS 动态改 lang

meta charset 必须是 head 第一个标签，title 不能缺

浏览器只扫描 前 1024 字节来确定编码。如果 被 或注释挡在后面，中文立刻变方框，刷新也救不回来。

常见错误现象：fetch 返回的 JSON 中文字段乱码、document.title 读出来是乱码、Lighthouse 报“Missing document language”。

实操建议：

• 紧贴 开始，前面不能有任何东西（包括空行）
• 别写 ——HTML5 已废弃，Chrome 120+ 直接忽略
• 是强制字段：没它，标签页显示“无标题文档”，爬虫当废页，微信 WebView 默认显示域名
• SPA 场景下， 必须是首屏 HTML 的真实内容，不能靠 JS 后续注入——否则 SSR hydration 会报 DOM mismatch

挂载容器要空、唯一、带 id，且不能塞初始 HTML

React/Vue/Angular 都靠这个节点启动。比如 create-react-app 默认找 id="root"，Vue 3 createApp(...).mount('#app') 绑定的是 id="app"。但很多人在里面写了一堆

Loading...

，结果框架初始化时清空整个容器，造成闪烁或冗余 DOM。

实操建议：

• 只放一个空的、带唯一 id 的容器：
  或
• 不要用 class 替代 id——框架 mount API 明确要求 CSS 选择器，.app 会匹配多个节点
• 若用 history.pushState 实现前端路由，必须加 ，否则相对路径资源（如 ./assets/main.js）在子路径下 404
• 开发阶段可用 直接引入 ESM，但生产环境务必构建为单个 .js 文件——避免模块加载失败导致白屏

静态资源路径必须用相对路径，file:// 下必挂本地服务

双击打开 index.html 报 Access to script at 'file:///xxx' from origin 'null'？这不是你 HTML 写错了，是浏览器安全策略：file:// 协议下，fetch、import()、甚至部分 都被拦截。

实操建议：

• 所有路径用相对路径：logo.png、../assets/style.css；绝对路径（/assets/main.js）在子路径部署时 100% 404
• 路径里别出现空格或中文——URL 编码后难调试，CI/CD 构建常失败
• 第三方库（Bootstrap、FontAwesome）一律硬写死在 index.html 的 或 底部，别塞进组件模板——构建工具根本没法解析变量
• 真想本地调试？起个最小 HTTP 服务：npx serve 或 python3 -m http.server 8000，别信 --disable-web-security——交付物不能依赖这种临时开关

真正容易被忽略的点是：骨架本身不跑逻辑，但它决定了整个 SPA 能不能稳住。比如 lang 错了，屏幕阅读器发音错、SEO 权重掉；charset 位置偏了，中文一加载就乱码，后续 JS 解析 JSON 也跟着崩；挂载容器里塞了初始 HTML，React hydrate 时先清空再渲染，用户看到闪一下才出来内容——这些都不是“功能 bug”，而是骨架层面的隐性缺陷，上线后很难定位。