第三方监控 SDK 必须在 <head> 最顶部内联注入，因为只有此处无任何字符的内联脚本才能捕获首屏渲染前所有事件（如 FP/FCP、早期 JS 错误等），否则会漏掉关键指标；外链需配合 document.write 或同步动态插入至 <head> 首位；CSP 下应采用 nonce 而非 hash；初始化须 try-catch + 超时熔断并检查全局变量就绪状态。
为什么第三方监控 SDK 必须在 <head> 最顶部内联注入
因为 HTML 解析器一旦开始解析文档，就立即执行 <script> 标签；只有位于 <head> 开头、**前面无任何字符（包括空白、注释、<meta>）** 的内联脚本，才能捕获首屏渲染前的所有事件（如 DOMContentLoaded 前的资源加载、JS 错误、FP/FCP 等）。否则会漏掉关键性能指标或未捕获的早期错误。
- 常见错误：把监控脚本塞进
<body>里、放在<meta charset="utf-8">后面、或用async/defer加载 —— 这些都会导致window.performance时间线已推进、document.readyState变更、甚至error事件已被丢弃 - 必须内联（不能
src外链）：外链脚本即使加blocking也会触发 parser blocking，而内联脚本能立即执行，且不增加额外请求 - 若必须外链（如合规要求分离代码），则需配合
document.write或同步动态插入：const s = document.createElement('script'); s.src = 'https://cdn.example.com/monitor.js'; document.head.insertBefore(s, document.head.firstChild);，但要确保该语句本身就在<head>顶上
document.write 在监控注入中的真实作用与风险
它不是“过时语法”，而是目前唯一能在 HTML 解析中途、<head> 任意位置**同步阻塞并写入脚本标签**的方式——前提是调用时机早于 <body> 开始解析。
- 仅适用于服务端模板或构建时注入：比如在 SSR 模板中写
<% if (env === 'prod') { %><script>...</script><% } %>，或 Vite 插件在transformIndexHtml钩子中直接拼字符串 - 绝对不能在 DOMContentLoaded 后或事件回调里调用：
document.write会清空整个文档，造成白屏 - 现代打包器（如 Vite）默认禁用
document.write，需显式配置build.rollupOptions.output.inlineDynamicImports = true并关闭build.ssr才能保留其行为 - 替代方案有限：用
document.head.insertBefore()动态插入 script 标签虽可行，但必须保证插入点在<head>第一个子节点之前，且脚本本身不能含async/defer
CSP 下如何让监控脚本不被拦截又不放行 unsafe-inline
靠 nonce + 内联脚本是最稳妥路径，strict-dynamic 在监控场景下极易失效。
-
script-src 'nonce-abc123' 'strict-dynamic'要求首屏脚本必须带nonce="abc123"，且后续所有动态创建的<script>（包括监控 SDK 自己插入的上报逻辑）才被信任；但多数监控 SDK 不识别 nonce，也不会自动继承 - 服务端每次响应必须生成唯一
nonce值（不能复用、不能硬编码），并在 HTTP 响应头和<script nonce="...">中保持一致 - 如果使用 Webpack/Vite 构建，需确保所有内联初始化代码（包括你写的监控注入逻辑）都包裹在带 nonce 的
<script>标签里，而非通过eval或new Function()执行 - 不要试图用
hash：监控脚本内容常含环境变量或时间戳，哈希值不可控，缓存和部署都易出错
SDK 初始化失败时如何静默兜底而不报错
监控 SDK 本身不该成为页面故障源 —— 它挂了，业务还得跑。所有初始化逻辑必须包裹在 try-catch 里，并设超时熔断。
立即学习“前端免费学习笔记（深入）”；
- 用
Promise.race([init(), new Promise((_, r) => setTimeout(() => r(), 1000))])防止 SDK 卡死主线程 - 检查全局变量是否就绪再调用：
if (typeof window.Sentry !== 'undefined') { Sentry.init({...}); }，避免ReferenceError - 对依赖 DOM 的 SDK（如某些行为采集），加
if (document.body)判断，否则延后到DOMContentLoaded后再试一次 - 不要用
onerror兜底：它无法捕获import()失败或fetch超时，只适合监听 JS 执行错误
真正难的是平衡：既要抢在首帧前注入，又要避开 CSP 和解析时机冲突；静默不是藏错误，而是把失败控制在可观察、可回溯的范围内。多数团队卡在 nonce 生成和 head 插入顺序上，而不是 SDK 本身。
