前端清单项目实战以 Cumulative Layout ShiftCLS为核心的视觉稳定性优化指南【免费下载链接】Front-End-Checklist The essential checklist for modern web development, for humans and AI agents项目地址: https://gitcode.com/gh_mirrors/fr/Front-End-ChecklistCumulative Layout Shift累计布局偏移简称 CLS是衡量页面视觉稳定性的 Core Web Vitals 指标它直接统计页面加载过程中未预期的内容位移是误点击、阅读中断和用户挫败感的首要来源。本指南以 Front-End-Checklist 仓库中的cumulative-layout-shift规则为核心骨架完整讲解 CLS 的评分阈值、六大常见成因、图片/广告位/字体/动画/动态内容五类实战修复方案以及基于web-vitals库与 PerformanceObserver 的测量与验证方法帮助你在现代前端项目中把 CLS 稳定压到 0.1 以下。CLS 是什么衡量未预期位移的视觉稳定性指标Cumulative Layout Shift 度量页面内容在加载过程中发生的未预期移动。所谓未预期指的是用户没有主动发起任何操作、页面元素却自行发生了位置变化。这类位移会造成三类直接伤害误点击用户正准备点击某个按钮时内容突然下移/右移点击落到了别的元素上阅读中断正在阅读的段落被插入的内容挤开视线被迫重找体验劣化页面跳动感让用户认为站点质量低劣、不够可信。一个良好的 CLS 分数意味着内容停留在用户期望它出现的位置。在 Front-End-Checklist 仓库中该规则被归类为performance类别下的web-vitals子类优先级为 high、难度为 intermediate、预估耗时 20 分钟定义见 SKILL.md 与完整规则页 cumulative-layout-shift.mdx。同时CLS 是 Core Web Vitals 三大指标之一与 LCP加载性能目标 2.5s、INP响应性目标 200ms并列。仓库的 core-web-vitals.mdx 清单将其目标明确为under 0.1并指出 CLS 主要由无尺寸图片、动态内容和晚加载字体造成。CLS 评分阈值判断好坏的标尺CLS 不是有或无而是一个连续分数。仓库规则中给出了权威的三档阈值分数评级用户体验0–0.1Good良好页面稳定无意外位移0.1–0.25Needs improvement需改进可感知的明显位移 0.25Poor较差显著的布局不稳定实际审计时的目标非常明确CLS 低于 0.1即视为良好。在 Chrome 的评分中任何大于 0.1 的分数都会被标记为需要改进超过 0.25 则为严重问题。布局偏移的六大常见成因与对策不同的成因对 CLS 的冲击程度不同仓库规则用一张表格给出了成因 → 影响 → 解法的完整对应关系成因影响程度解决方案图片缺少宽高尺寸高始终设置 width/height广告位与嵌入式内容embeds高预占容器空间Web 字体加载中使用 font-display: swap动态内容注入中使用占位符/骨架屏动画低使用 transform/opacity这套优先级很有用高影响因子先修。图片无尺寸和广告位不预占空间是最常见的 CLS 来源也是收益最大的修复点字体和动态内容次之动画虽然也会引起位移但只影响局部且低频属于低优先级。图片最可靠的 CLS 修复手段为什么图片没有尺寸必然引起位移当浏览器解析 HTML 时它并不知道图片的尺寸——如果img没有显式宽高浏览器会先渲染一个0 高度的占位符图片下载完成后布局再跳一次这次跳跃就被计入了 CLS。仓库的 dimensions.mdx 规则明确写道Missing dimensions are the leading cause of Cumulative Layout Shift from images缺少尺寸是图片导致 CLS 的头号原因并指出现代浏览器Chrome 79、Firefox 71、Safari 15会自动从 HTML 的width/height属性推导出aspect-ratio相当于内部应用了img { aspect-ratio: attr(width) / attr(height); }这意味着只要 HTML 属性存在即使在 CSS 加载之前浏览器也能预占正确空间——这是为什么属性必须写在 HTML 上而非只靠 CSS 的关键原因。基础写法显式宽高 响应式兜底!-- 始终指定 width 和 height -- img srchero.jpg altHero image width1200 height600 loadinglazy !-- 或者使用 aspect-ratio CSS -- img srchero.jpg altHero image styleaspect-ratio: 16/9; width: 100%; height: auto; 注意属性值必须与图片真实的内在宽高比一致不能随意填数字否则浏览器按错误比例预占空间依然会产生偏移。要让图片既保留预占空间又保持响应式配合以下 CSSimg { max-width: 100%; height: auto; /* 覆盖 height 属性实现响应式缩放 */ }React / Next.js 场景在 React/Next.js 中next/image组件在编译期强制要求width和height或fill属性并自动处理布局偏移预防import Image from next/image function Hero() { return ( Image src/hero.jpg altHero image width{1200} height{600} priority // 尺寸属性防止布局偏移 / ) }对于动态尺寸的图片从已知宽高比反推标准化尺寸即可。仓库 dimensions.mdx 给出了一个AspectImage组件模式把16/9、4/3、1/1等比例映射到固定像素值再用maxWidth: 100%保持响应。例外与豁免并非所有图片都要改从源码结构看dimensions规则特意声明了四类低风险豁免场景避免审计时误伤CSS 背景图片尺寸由background-size和容器尺寸控制HTML 属性不适用内联 SVG 图标或通过img加载、CSS 已设绝对尺寸如width: 24px——位移风险可忽略微型装饰性 SVG 分隔线CSS 已提供稳定尺寸、且不含内容语义固定高度容器内图片容器本身已预占空间overflow: hidden 前提下无所谓图片尺寸。广告位与动态内容先占坑后填内容广告、Banner、推荐位这类异步加载的内容是仅次于图片的 CLS 高发区。核心思路是在内容到达之前用固定尺寸或最小高度把位置占住。// 为广告预占空间 function AdBanner() { return ( div style{{ minHeight: 250px, width: 300px, backgroundColor: #f0f0f0, }} {/* 广告在此加载不会引起位移 */} /div ) } // 骨架屏加载内容 function ArticleCard({ isLoading, article }) { if (isLoading) { return ( div classNamearticle-card div classNameskeleton style{{ height: 200px }} / div classNameskeleton style{{ height: 24px, width: 80% }} / div classNameskeleton style{{ height: 16px, width: 60% }} / /div ) } return ( div classNamearticle-card img src{article.image} alt{article.title} width{300} height{200} / h2{article.title}/h2 p{article.excerpt}/p /div ) }骨架屏skeleton用与最终内容同尺寸的灰色占位块撑开布局数据到达后内容原地替换、不产生位移广告位则用minHeight预先声明高度。图片尺寸属性在骨架场景同样必须保留width{300} height{200}因为懒加载图片进入视口时若无尺寸依然会引发位移——这一点在 dimensions.mdx 的 relatedRules 中与lazy-loading、offscreen-lazy规则做了明确关联。字体加载消灭 FOIT/FOUT 引起的跳动字体是 CLS 的中等影响因子。自定义字体与回退字体fallback的字宽、行高不同当字体加载完成后替换显示就会引起整段文字的位置跳动。仓库的 font-loading.mdx 规则从晚发现字体藏在 CSS 里、浏览器发现得晚切入给出三层策略。font-display: swap与字体度量对齐/* 使用 font-display 防止 FOIT/FOUT 位移 */ font-face { font-family: CustomFont; src: url(/fonts/custom.woff2) format(woff2); font-display: swap; /* 立即显示回退字体加载完成后替换 */ size-adjust: 100%; /* 匹配回退字体度量 */ ascent-override: 90%; descent-override: 20%; } /* 使用相似的回退字体 */ body { font-family: CustomFont, Arial, sans-serif; }font-display: swap让文本先用系统回退字体渲染用户能立即阅读避免 FOIT 隐形文字自定义字体就绪后再替换ascent-override/descent-override/size-adjust用于对齐回退字体与自定义字体的度量让替换发生时行高与字宽基本一致从而把 FOUT 阶段的跳动压到最小还应配合link relpreload href/fonts/my-font.woff2 asfont typefont/woff2 crossorigin提前发现关键字体并优先使用 WOFF2 格式压缩率显著优于 WOFF/TTF。Next.js 内置字体优化import { Inter } from next/font/google const inter Inter({ subsets: [latin], display: swap, // 防止字体加载引起的布局偏移 }) export default function RootLayout({ children }) { return ( html className{inter.className} body{children}/body /html ) }Next.js 的字体模块会在构建期自托管字体并自动生成度量覆盖display: swap显式开启回退显示。仓库自身也大量使用了这类现代字体策略来保证站点自身的 CLS。动画只动 transform 和 opacityCSS 动画是 CLS 的低影响因子但写法不当同样会造成局部位移。原则是永远不要让动画触碰会触发布局的属性margin、padding、width、height、top/left 等只使用合成器属性。/* 错误动画布局属性 */ .bad-animation { animation: slide-bad 0.3s ease-out; } keyframes slide-bad { from { margin-left: -100px; } /* 引起布局偏移 */ to { margin-left: 0; } } /* 正确使用 transform */ .good-animation { animation: slide-good 0.3s ease-out; } keyframes slide-good { from { transform: translateX(-100px); } /* 不引起布局偏移 */ to { transform: translateX(0); } }margin-left的动画每帧都重新计算布局而transform: translateX()走 GPU 合成管线不触发布局与绘制视觉位移也不会计入 CLS。同类可安全动画的属性还包括opacity合成属性与transform族translate/scale/rotate。动态内容注入不要在既有内容上方插内容向上方注入内容是新手最容易踩的坑useEffect或setTimeout触发后才渲染的 Banner、Cookie 弹窗、公告条会把下方已稳定的内容整体推下去。仓库规则给出了显式的前后对比// 错误在内容上方插入 banner function Page() { const [showBanner, setShowBanner] useState(false) useEffect(() { // 当 banner 出现时会引起布局偏移 setTimeout(() setShowBanner(true), 1000) }, []) return ( div {showBanner Banner /} {/* 把内容推下去 */} Content / /div ) } // 正确为 banner 预占空间 function Page() { const [showBanner, setShowBanner] useState(false) return ( div div style{{ minHeight: 60px }} {showBanner Banner /} /div Content / /div ) }两条修复原则内容插入点尽量选在视口下方或既有内容之后避免推挤已读区域无法避免时用minHeight预占固定高度让 Banner 出现时不改变下方元素位置。同样适用于 Cookie 横幅、通知条、轮播等任何迟到的界面元素。测量 CLSlab 数据与 field 数据两条路修复之前必须先测量仓库规则同时提供了基于web-vitals库的高级 API 与底层 PerformanceObserver 两种方案// 使用 web-vitals 库 import { onCLS } from web-vitals onCLS(metric { console.log(CLS:, metric.value) // 上报到分析平台 if (metric.value 0.1) { console.warn(CLS exceeds threshold, metric.entries) } }) // 调试是哪些元素引起的位移 new PerformanceObserver(list { for (const entry of list.getEntries()) { if (entry.hadRecentInput) continue // 忽略用户操作触发的位移 console.log(Layout shift:, { value: entry.value, sources: entry.sources?.map(s ({ node: s.node, currentRect: s.currentRect, previousRect: s.previousRect })) }) } }).observe({ type: layout-shift, buffered: true })关键细节hadRecentInput用于过滤用户主动操作引发的位移如点击展开菜单只有未预期位移才计入 CLSentry.sources精确列出每个偏移源的节点与前后矩形currentRect/previousRect是定位哪个元素在动的核心调试数据buffered: true让观察器回放页面加载早期已发生的位移事件避免漏测。对应的标准验证手段见规则文档的 Verification 章节自动化检查运行 Lighthouse在 Performance 面板查看 CLS 分数使用 Chrome DevTools 的 Performance 面板录制页面加载查看布局位移标记通过 PageSpeed Insights 查看真实用户field数据在 DevTools 的 Rendering 面板开启Layout Shift Regions高亮可直观看到位移发生的区域。手动检查在慢速网络Throttling下测试——时序型位移依赖加载时机的位移只有慢网下才会暴露用 Real User MonitoringRUM持续监控生产环境的 CLS 分布。在项目与 Agent 审计中的落地方式Front-End-Checklist 把这条规则做成了面向人和 AI Agent的双形态人类审计者使用 SKILL.md 中提炼的 Quick Reference目标 0.1、图片/嵌入必须设尺寸、为广告与动态内容预占空间、用 transform 动画而 AI Agent 则依据其中定义的 Check / Fix / Explain / Code Review 四类提示词工作Check用 Lighthouse 或 PageSpeed Insights 测量验证分数低于 0.1Fix用尺寸为图片/嵌入预占空间、采用 font-display 策略、避免在既有内容上方注入内容Explain向团队解释 CLS 的测量原理与用户体验影响Code Review审查相关路由、资源与加载行为精确指出是哪个文件、哪个请求、哪一步渲染增加了不必要的网络/CPU/布局开销并描述确认问题的测量方法。SKILL.md 的 metadata 还强调aiContext只有在审计慢页面加载、重资源或渲染延迟问题时才启用该技能并且必须先通过 DevTools、Lighthouse 或 field 数据确认真实瓶颈再给出修改建议——避免无证据乱开药方。这条规则在仓库规则体系中与first-contentful-paintFCP、largest-contentful-paintLCP、dimensions互为 relatedRules实际审计时通常成组评审见 cumulative-layout-shift.mdx 的 relatedRules 声明。结语一条可复用的 CLS 修复工作流综合仓库规则与清单内容推荐按以下顺序落地测量Lighthouse PageSpeed Insights PerformanceObserver 定位偏移源修高影响项所有img补width/height属性值与真实宽高比一致广告位与动态内容用minHeight预占空间修中影响项font-face加font-display: swap并对齐字体度量Next.js 项目用字体模块修低影响项动画改用transform/opacity验证慢网重测 RUM 持续监控确认 CLS 0.1 且无回归。每一步都可在 cumulative-layout-shift.mdx、dimensions.mdx、font-loading.mdx 与 core-web-vitals.mdx 中找到完整实现与验证依据直接对照仓库即可复现整套优化。【免费下载链接】Front-End-Checklist The essential checklist for modern web development, for humans and AI agents项目地址: https://gitcode.com/gh_mirrors/fr/Front-End-Checklist创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
前端清单项目实战：以 Cumulative Layout Shift（CLS）为核心的视觉稳定性优化指南
前端清单项目实战以 Cumulative Layout ShiftCLS为核心的视觉稳定性优化指南【免费下载链接】Front-End-Checklist The essential checklist for modern web development, for humans and AI agents项目地址: https://gitcode.com/gh_mirrors/fr/Front-End-ChecklistCumulative Layout Shift累计布局偏移简称 CLS是衡量页面视觉稳定性的 Core Web Vitals 指标它直接统计页面加载过程中未预期的内容位移是误点击、阅读中断和用户挫败感的首要来源。本指南以 Front-End-Checklist 仓库中的cumulative-layout-shift规则为核心骨架完整讲解 CLS 的评分阈值、六大常见成因、图片/广告位/字体/动画/动态内容五类实战修复方案以及基于web-vitals库与 PerformanceObserver 的测量与验证方法帮助你在现代前端项目中把 CLS 稳定压到 0.1 以下。CLS 是什么衡量未预期位移的视觉稳定性指标Cumulative Layout Shift 度量页面内容在加载过程中发生的未预期移动。所谓未预期指的是用户没有主动发起任何操作、页面元素却自行发生了位置变化。这类位移会造成三类直接伤害误点击用户正准备点击某个按钮时内容突然下移/右移点击落到了别的元素上阅读中断正在阅读的段落被插入的内容挤开视线被迫重找体验劣化页面跳动感让用户认为站点质量低劣、不够可信。一个良好的 CLS 分数意味着内容停留在用户期望它出现的位置。在 Front-End-Checklist 仓库中该规则被归类为performance类别下的web-vitals子类优先级为 high、难度为 intermediate、预估耗时 20 分钟定义见 SKILL.md 与完整规则页 cumulative-layout-shift.mdx。同时CLS 是 Core Web Vitals 三大指标之一与 LCP加载性能目标 2.5s、INP响应性目标 200ms并列。仓库的 core-web-vitals.mdx 清单将其目标明确为under 0.1并指出 CLS 主要由无尺寸图片、动态内容和晚加载字体造成。CLS 评分阈值判断好坏的标尺CLS 不是有或无而是一个连续分数。仓库规则中给出了权威的三档阈值分数评级用户体验0–0.1Good良好页面稳定无意外位移0.1–0.25Needs improvement需改进可感知的明显位移 0.25Poor较差显著的布局不稳定实际审计时的目标非常明确CLS 低于 0.1即视为良好。在 Chrome 的评分中任何大于 0.1 的分数都会被标记为需要改进超过 0.25 则为严重问题。布局偏移的六大常见成因与对策不同的成因对 CLS 的冲击程度不同仓库规则用一张表格给出了成因 → 影响 → 解法的完整对应关系成因影响程度解决方案图片缺少宽高尺寸高始终设置 width/height广告位与嵌入式内容embeds高预占容器空间Web 字体加载中使用 font-display: swap动态内容注入中使用占位符/骨架屏动画低使用 transform/opacity这套优先级很有用高影响因子先修。图片无尺寸和广告位不预占空间是最常见的 CLS 来源也是收益最大的修复点字体和动态内容次之动画虽然也会引起位移但只影响局部且低频属于低优先级。图片最可靠的 CLS 修复手段为什么图片没有尺寸必然引起位移当浏览器解析 HTML 时它并不知道图片的尺寸——如果img没有显式宽高浏览器会先渲染一个0 高度的占位符图片下载完成后布局再跳一次这次跳跃就被计入了 CLS。仓库的 dimensions.mdx 规则明确写道Missing dimensions are the leading cause of Cumulative Layout Shift from images缺少尺寸是图片导致 CLS 的头号原因并指出现代浏览器Chrome 79、Firefox 71、Safari 15会自动从 HTML 的width/height属性推导出aspect-ratio相当于内部应用了img { aspect-ratio: attr(width) / attr(height); }这意味着只要 HTML 属性存在即使在 CSS 加载之前浏览器也能预占正确空间——这是为什么属性必须写在 HTML 上而非只靠 CSS 的关键原因。基础写法显式宽高 响应式兜底!-- 始终指定 width 和 height -- img srchero.jpg altHero image width1200 height600 loadinglazy !-- 或者使用 aspect-ratio CSS -- img srchero.jpg altHero image styleaspect-ratio: 16/9; width: 100%; height: auto; 注意属性值必须与图片真实的内在宽高比一致不能随意填数字否则浏览器按错误比例预占空间依然会产生偏移。要让图片既保留预占空间又保持响应式配合以下 CSSimg { max-width: 100%; height: auto; /* 覆盖 height 属性实现响应式缩放 */ }React / Next.js 场景在 React/Next.js 中next/image组件在编译期强制要求width和height或fill属性并自动处理布局偏移预防import Image from next/image function Hero() { return ( Image src/hero.jpg altHero image width{1200} height{600} priority // 尺寸属性防止布局偏移 / ) }对于动态尺寸的图片从已知宽高比反推标准化尺寸即可。仓库 dimensions.mdx 给出了一个AspectImage组件模式把16/9、4/3、1/1等比例映射到固定像素值再用maxWidth: 100%保持响应。例外与豁免并非所有图片都要改从源码结构看dimensions规则特意声明了四类低风险豁免场景避免审计时误伤CSS 背景图片尺寸由background-size和容器尺寸控制HTML 属性不适用内联 SVG 图标或通过img加载、CSS 已设绝对尺寸如width: 24px——位移风险可忽略微型装饰性 SVG 分隔线CSS 已提供稳定尺寸、且不含内容语义固定高度容器内图片容器本身已预占空间overflow: hidden 前提下无所谓图片尺寸。广告位与动态内容先占坑后填内容广告、Banner、推荐位这类异步加载的内容是仅次于图片的 CLS 高发区。核心思路是在内容到达之前用固定尺寸或最小高度把位置占住。// 为广告预占空间 function AdBanner() { return ( div style{{ minHeight: 250px, width: 300px, backgroundColor: #f0f0f0, }} {/* 广告在此加载不会引起位移 */} /div ) } // 骨架屏加载内容 function ArticleCard({ isLoading, article }) { if (isLoading) { return ( div classNamearticle-card div classNameskeleton style{{ height: 200px }} / div classNameskeleton style{{ height: 24px, width: 80% }} / div classNameskeleton style{{ height: 16px, width: 60% }} / /div ) } return ( div classNamearticle-card img src{article.image} alt{article.title} width{300} height{200} / h2{article.title}/h2 p{article.excerpt}/p /div ) }骨架屏skeleton用与最终内容同尺寸的灰色占位块撑开布局数据到达后内容原地替换、不产生位移广告位则用minHeight预先声明高度。图片尺寸属性在骨架场景同样必须保留width{300} height{200}因为懒加载图片进入视口时若无尺寸依然会引发位移——这一点在 dimensions.mdx 的 relatedRules 中与lazy-loading、offscreen-lazy规则做了明确关联。字体加载消灭 FOIT/FOUT 引起的跳动字体是 CLS 的中等影响因子。自定义字体与回退字体fallback的字宽、行高不同当字体加载完成后替换显示就会引起整段文字的位置跳动。仓库的 font-loading.mdx 规则从晚发现字体藏在 CSS 里、浏览器发现得晚切入给出三层策略。font-display: swap与字体度量对齐/* 使用 font-display 防止 FOIT/FOUT 位移 */ font-face { font-family: CustomFont; src: url(/fonts/custom.woff2) format(woff2); font-display: swap; /* 立即显示回退字体加载完成后替换 */ size-adjust: 100%; /* 匹配回退字体度量 */ ascent-override: 90%; descent-override: 20%; } /* 使用相似的回退字体 */ body { font-family: CustomFont, Arial, sans-serif; }font-display: swap让文本先用系统回退字体渲染用户能立即阅读避免 FOIT 隐形文字自定义字体就绪后再替换ascent-override/descent-override/size-adjust用于对齐回退字体与自定义字体的度量让替换发生时行高与字宽基本一致从而把 FOUT 阶段的跳动压到最小还应配合link relpreload href/fonts/my-font.woff2 asfont typefont/woff2 crossorigin提前发现关键字体并优先使用 WOFF2 格式压缩率显著优于 WOFF/TTF。Next.js 内置字体优化import { Inter } from next/font/google const inter Inter({ subsets: [latin], display: swap, // 防止字体加载引起的布局偏移 }) export default function RootLayout({ children }) { return ( html className{inter.className} body{children}/body /html ) }Next.js 的字体模块会在构建期自托管字体并自动生成度量覆盖display: swap显式开启回退显示。仓库自身也大量使用了这类现代字体策略来保证站点自身的 CLS。动画只动 transform 和 opacityCSS 动画是 CLS 的低影响因子但写法不当同样会造成局部位移。原则是永远不要让动画触碰会触发布局的属性margin、padding、width、height、top/left 等只使用合成器属性。/* 错误动画布局属性 */ .bad-animation { animation: slide-bad 0.3s ease-out; } keyframes slide-bad { from { margin-left: -100px; } /* 引起布局偏移 */ to { margin-left: 0; } } /* 正确使用 transform */ .good-animation { animation: slide-good 0.3s ease-out; } keyframes slide-good { from { transform: translateX(-100px); } /* 不引起布局偏移 */ to { transform: translateX(0); } }margin-left的动画每帧都重新计算布局而transform: translateX()走 GPU 合成管线不触发布局与绘制视觉位移也不会计入 CLS。同类可安全动画的属性还包括opacity合成属性与transform族translate/scale/rotate。动态内容注入不要在既有内容上方插内容向上方注入内容是新手最容易踩的坑useEffect或setTimeout触发后才渲染的 Banner、Cookie 弹窗、公告条会把下方已稳定的内容整体推下去。仓库规则给出了显式的前后对比// 错误在内容上方插入 banner function Page() { const [showBanner, setShowBanner] useState(false) useEffect(() { // 当 banner 出现时会引起布局偏移 setTimeout(() setShowBanner(true), 1000) }, []) return ( div {showBanner Banner /} {/* 把内容推下去 */} Content / /div ) } // 正确为 banner 预占空间 function Page() { const [showBanner, setShowBanner] useState(false) return ( div div style{{ minHeight: 60px }} {showBanner Banner /} /div Content / /div ) }两条修复原则内容插入点尽量选在视口下方或既有内容之后避免推挤已读区域无法避免时用minHeight预占固定高度让 Banner 出现时不改变下方元素位置。同样适用于 Cookie 横幅、通知条、轮播等任何迟到的界面元素。测量 CLSlab 数据与 field 数据两条路修复之前必须先测量仓库规则同时提供了基于web-vitals库的高级 API 与底层 PerformanceObserver 两种方案// 使用 web-vitals 库 import { onCLS } from web-vitals onCLS(metric { console.log(CLS:, metric.value) // 上报到分析平台 if (metric.value 0.1) { console.warn(CLS exceeds threshold, metric.entries) } }) // 调试是哪些元素引起的位移 new PerformanceObserver(list { for (const entry of list.getEntries()) { if (entry.hadRecentInput) continue // 忽略用户操作触发的位移 console.log(Layout shift:, { value: entry.value, sources: entry.sources?.map(s ({ node: s.node, currentRect: s.currentRect, previousRect: s.previousRect })) }) } }).observe({ type: layout-shift, buffered: true })关键细节hadRecentInput用于过滤用户主动操作引发的位移如点击展开菜单只有未预期位移才计入 CLSentry.sources精确列出每个偏移源的节点与前后矩形currentRect/previousRect是定位哪个元素在动的核心调试数据buffered: true让观察器回放页面加载早期已发生的位移事件避免漏测。对应的标准验证手段见规则文档的 Verification 章节自动化检查运行 Lighthouse在 Performance 面板查看 CLS 分数使用 Chrome DevTools 的 Performance 面板录制页面加载查看布局位移标记通过 PageSpeed Insights 查看真实用户field数据在 DevTools 的 Rendering 面板开启Layout Shift Regions高亮可直观看到位移发生的区域。手动检查在慢速网络Throttling下测试——时序型位移依赖加载时机的位移只有慢网下才会暴露用 Real User MonitoringRUM持续监控生产环境的 CLS 分布。在项目与 Agent 审计中的落地方式Front-End-Checklist 把这条规则做成了面向人和 AI Agent的双形态人类审计者使用 SKILL.md 中提炼的 Quick Reference目标 0.1、图片/嵌入必须设尺寸、为广告与动态内容预占空间、用 transform 动画而 AI Agent 则依据其中定义的 Check / Fix / Explain / Code Review 四类提示词工作Check用 Lighthouse 或 PageSpeed Insights 测量验证分数低于 0.1Fix用尺寸为图片/嵌入预占空间、采用 font-display 策略、避免在既有内容上方注入内容Explain向团队解释 CLS 的测量原理与用户体验影响Code Review审查相关路由、资源与加载行为精确指出是哪个文件、哪个请求、哪一步渲染增加了不必要的网络/CPU/布局开销并描述确认问题的测量方法。SKILL.md 的 metadata 还强调aiContext只有在审计慢页面加载、重资源或渲染延迟问题时才启用该技能并且必须先通过 DevTools、Lighthouse 或 field 数据确认真实瓶颈再给出修改建议——避免无证据乱开药方。这条规则在仓库规则体系中与first-contentful-paintFCP、largest-contentful-paintLCP、dimensions互为 relatedRules实际审计时通常成组评审见 cumulative-layout-shift.mdx 的 relatedRules 声明。结语一条可复用的 CLS 修复工作流综合仓库规则与清单内容推荐按以下顺序落地测量Lighthouse PageSpeed Insights PerformanceObserver 定位偏移源修高影响项所有img补width/height属性值与真实宽高比一致广告位与动态内容用minHeight预占空间修中影响项font-face加font-display: swap并对齐字体度量Next.js 项目用字体模块修低影响项动画改用transform/opacity验证慢网重测 RUM 持续监控确认 CLS 0.1 且无回归。每一步都可在 cumulative-layout-shift.mdx、dimensions.mdx、font-loading.mdx 与 core-web-vitals.mdx 中找到完整实现与验证依据直接对照仓库即可复现整套优化。【免费下载链接】Front-End-Checklist The essential checklist for modern web development, for humans and AI agents项目地址: https://gitcode.com/gh_mirrors/fr/Front-End-Checklist创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
