web-vitals是JavaScript库，非HTML标签或属性，需通过脚本调用onLCP/onCLS/onINP等函数采集指标；仅引入script不调用函数将无法获取数据，且须注意执行时机、buffered配置及手动上报逻辑。
web-vitals 不是 HTML 标签或属性，不能“写在 HTML 里”直接生效。它是一个 JavaScript 库，必须通过脚本加载并调用函数才能采集指标。把 web-vitals 当成 HTML 功能来用，会完全收不到数据。
onCLS/onINP/onLCP 这些函数必须在 JS 中调用
HTML 本身不提供 Web Vitals 指标采集能力。浏览器原生的 PerformanceObserver 是底层机制，但封装、兼容性处理、阈值判断、重复触发抑制等逻辑全在 web-vitals 的 JS 函数里。
常见错误现象：
- 只在 HTML 里加
<script src="web-vitals.js"></script>，但没调任何onCLS()或getLCP()—— 页面静默，控制台无输出，上报为零 - 把
onLCP(console.log)写在<script>标签里，但脚本放在<head>且没加defer—— 可能因 DOM 未就绪导致部分指标丢失（尤其 CLS）
正确做法：
- 确保脚本在
<body>底部，或使用defer属性 - 每个指标只调用一次，例如：
import { onCLS, onINP, onLCP } from 'web-vitals'; onCLS(sendToAnalytics); onINP(sendToAnalytics); onLCP(sendToAnalytics); - 不要在同一个页面多次执行
onCLS(...)—— 会创建多个PerformanceObserver，造成内存泄漏
CDN 引入时必须用 type="module" 或 IIFE 构建
直接 <script src="https://unpkg.com/web-vitals@5/dist/web-vitals.iife.js"></script> 可以用，但若用 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又用<script src>，容易重复加载
指标上报必须手动实现，HTML 不自动发送数据
web-vitals 库只负责采集和计算，不内置上报逻辑。你看到的 console.log(metric) 只是演示，生产环境必须替换为真实上报函数。
文章转信息图。将文章/笔记转化为手机可读的 HTML 信息图，自动匹配视觉风格。触发场景：文章转图、笔记转图、信息图、转小红书图、做张图、可视化这篇文章、文生图。
容易踩的坑：
- 直接传
console.log上线 —— 控制台刷屏，但服务器一条数据没收到 - 每个指标都单独发请求（
fetch('/log', {body: JSON.stringify(m)})）—— 触发多次网络请求，可能被浏览器限流或丢弃 - 没做采样，在高流量站点导致日志爆炸（建议用
Math.random() 控制 10% 采样率）
推荐做法：
- 用
navigator.sendBeacon()上报，保证页面卸载前也能发出 - 聚合多个指标再上报，例如 3 个指标攒够再发一次
- 上报前加基础过滤：
if (metric.value > 0 && metric.id)，避免无效条目
CLS 值不准？检查是否漏了 layout-shift 的 buffered 配置
CLS 计算依赖所有历史 layout-shift 条目，如果 PerformanceObserver 创建太晚，会错过首屏布局抖动。这不是 bug，是配置问题。
根本原因：
-
onCLS()内部默认启用buffered: true，但前提是脚本尽早执行（最好在<head>用defer加载） - 如果脚本等到
DOMContentLoaded才执行，首屏图片加载、字体渲染引发的 layout shift 已发生，无法捕获
验证方式：打开 Chrome DevTools → Application → Clear storage → 刷新页面 → 看 Performance tab 里是否有 layout-shift 条目早于 JS 执行时间
解决办法：
- 把监控脚本放到
<head>，加defer（不是async，要保证执行顺序） - 不用
onCLS而改用getCLS+ 自定义 observer，自己控制buffered: true初始化时机 - 对 SSR 页面，服务端可注入初始
cls=0占位，避免客户端首次计算偏差
