纯CSS变量无法自动响应滚动，必须由JS读取scrollTop并计算进度后主动写入--scroll-progress；需用requestAnimationFrame节流、缓存scrollHeight、处理iOS Safari地址栏变化等边界情况。
纯 CSS 变量（--scroll-progress）本身不能“自动响应”滚动，必须靠 JS 读取滚动值并主动写入；否则变量永远静止在初始值，进度条不会动。
为什么不能只靠 :root 变量声明就实现滚动进度
CSS 自定义属性是静态的，没有监听能力。你写 :root { --scroll-progress: 0; }，它就一直是 0，除非 JS 调用 document.documentElement.style.setProperty('--scroll-progress', value) 显式更新。伪元素或 width: calc(var(--scroll-progress) * 100%) 只是“消费”变量，不负责“产生”变量。
- 常见错误：把
--scroll-progress写进:root后就以为完事，结果进度条始终为 0% - 纯 CSS 的
scroll()时间线不输出可读数值，无法绑定到变量上 -
@property声明类型（如inherits: false; syntax: '<number>'</number>）能让变量参与动画，但依然要 JS 驱动初始值和更新
JS 必须做的三件事：读、算、写
滚动进度本质是比例计算：scrollTop / (scrollHeight - clientHeight)，JS 不仅要算，还要安全写入 CSS 变量，并处理边界和性能问题。
- 统一读
document.documentElement.scrollTop（window.scrollY在 iOS Safari 有延迟，document.body.scrollTop在现代浏览器常为 0） - 分母用
document.documentElement.scrollHeight - window.innerHeight，不是body.scrollHeight - 写入时加
Math.min(1, Math.max(0, progress))防 NaN 或溢出（比如 DOM 动态加载后scrollHeight突然变小） - 用
requestAnimationFrame节流更新，避免 scroll 事件高频触发导致 layout thrashing
transform: scaleX() 比 width 更可靠
直接改 style.width 会覆盖 CSS 过渡、渐变背景、伪元素等效果；而用 CSS 变量驱动 transform: scaleX(var(--scroll-progress))，既保留样式层控制权，又触发 GPU 合成，更顺滑。
立即学习“前端免费学习笔记（深入）”；
- 进度条容器必须设
position: fixed; top: 0; left: 0; height: 3px; - 内部条元素推荐用
overflow: hidden防止内容撑开或溢出 - CSS 中写
transform: scaleX(var(--scroll-progress)); transform-origin: left center;，避免缩放中心偏移 - 别漏
will-change: transform，提前提示浏览器启用合成层
移动端 Safari 的两个隐藏陷阱
iOS Safari 地址栏收起/展开时会改变 window.innerHeight，但 scrollTop 不同步更新，导致进度跳变甚至倒退；这不是 bug，是它的 UI 行为逻辑。
- 必须监听
resize事件，重新缓存maxScrollHeight = document.documentElement.scrollHeight - 滚动中不要反复读
scrollHeight——它只在 DOM 变化（如图片加载完成）时才变，缓存一次足够 - 别依赖
passive: false强制阻止默认行为，iOS 上可能被忽略；加{ passive: true }是底线
最易被忽略的是：变量名拼错、单位漏写（如传 30 却没带 deg）、scrollHeight 缓存未重读、以及忘记在 fixed 容器里设 top: 0 —— 这些都会让进度条“看起来写了，但就是不动”。
