HTML性能监控：WebVitals实用指南

Web Vitals 性能监控并非通过 HTML 标签或属性即可启用，而是一个依赖 JavaScript 精准执行时机、正确调用 `onCLS`/`onLCP`/`onINP` 等函数、合理配置 `buffered` 选项并手动实现健壮上报逻辑的系统性工程——稍有疏忽（如仅引入脚本却不调用函数、脚本加载过晚导致 CLS 指标丢失、直接使用 `console.log` 上线或未做采样与聚合），就会造成数据静默缺失、内存泄漏或日志爆炸，真正落地的关键在于 JS 初始化顺序、PerformanceObserver 的生命周期管理与上报链路的可靠性三者严丝合缝的协同。

web-vitals 不是 HTML 标签或属性，不能“写在 HTML 里”直接生效。它是一个 JavaScript 库，必须通过脚本加载并调用函数才能采集指标。把 web-vitals 当成 HTML 功能来用，会完全收不到数据。

onCLS/onINP/onLCP 这些函数必须在 JS 中调用

HTML 本身不提供 Web Vitals 指标采集能力。浏览器原生的 PerformanceObserver 是底层机制，但封装、兼容性处理、阈值判断、重复触发抑制等逻辑全在 web-vitals 的 JS 函数里。

常见错误现象：

• 只在 HTML 里加 ，但没调任何 onCLS() 或 getLCP() —— 页面静默，控制台无输出，上报为零
• 把 onLCP(console.log) 写在 可以用，但若用 ES 模块语法（如 import { onLCP } from '...'），必须配合 type="module"，否则报 Uncaught SyntaxError: Cannot use import statement outside a module。

  国内推荐用字节跳动 CDN（稳定、免跨域）：

  <script type="module">
    import { onCLS, onINP, onLCP } from 'https://lf3-cdn-tos.bytecdntp.com/cdn/expire-1-M/web-vitals/3.1.1/web-vitals.attribution.js';
    onCLS(console.log);
  </script>

  注意：

  • web-vitals.attribution.js 比标准版大 1.5KB（brotli 后），仅在需要归因调试时才用
  • 如果项目不支持模块化，用 iife 构建 + 全局变量 webVitals，例如：webVitals.onLCP(...)
  • 不要混用：既用 import 又用