用history.scrollRestoration控制刷新后页面滚动位置

别再让长列表刷新后乱跳了：手把手搞定滚动位置控制

在日常前端开发中，特别是处理长列表或表单页面时，常会遇到这样的情况：用户向下滚动多屏后，执行回退、刷新等操作，页面“嗖”地跳回顶部，或跳到一个遮挡内容的莫名其妙位置。用户体验因此大打折扣。

浏览器本身提供了记忆滚动位置的能力，即 history.scrollRestoration。但若需精确控制，比如希望每次刷新后强制用户回到顶部，或避免虚拟列表中位置错乱，就不能仅依赖浏览器的默认行为。

具体怎么做？

第一步是告知浏览器：此页面的滚动位置由开发者接管。通过设置 history.scrollRestoration = 'manual'，即可禁用浏览器在前/后退及刷新时自动恢复滚动位置的默认行为。默认值为 'auto'，改为 'manual' 后，浏览器不再尝试恢复 window.scrollY。但需注意：此设置并非强制置顶，仅是取消自动恢复。仍需手动调用 window.scrollTo(0, 0) 才能确保真正回顶。该设置只影响“前进/后退”和“刷新”两类 history 导航的默认行为，页面内正常滚动逻辑不受影响。

核心原理：scrollRestoration = 'manual' 只是关闭“自动恢复”开关，后续所有滚动行为均由 JavaScript 显式控制。它仅提供取消默认行为的承诺，实际需开发者补充事件处理逻辑。

为什么仅设置 manual 不够？

问题在于：单纯设置 scrollRestoration = 'manual' 并不等同于“每次刷新都滚到顶部”。某些场景下，用户仍可能看到非预期滚动位置。

• 浏览器行为差异：页面首次加载后，用户向下滚动，然后手动刷新（F5 或地址栏回车）。若没有额外干预，scrollTo(0, 0) 未被触发，页面将从浏览器上次记录的 scrollY 开始渲染。注意，scrollRestoration = 'manual' 仅约束 history 导航，对刷新初始状态不起直接强制作用。
• iOS Safari 特殊情形：某些 iOS Safari 版本中，beforeunload 事件触发时机不稳定，导致刷新前未能及时执行 scrollTo(0, 0)。
• 编程式刷新：使用 location.reload() 进行编程式刷新时，beforeunload 事件不一定触发，尤其在没有用户交互的上下文中。

因此，scrollRestoration = 'manual' 仅是第一步，可靠方案需组合其他手段。

必杀技：beforeunload + pageshow 组合

确保持刷新后不错位的方案，依赖两个事件的组合：

• beforeunload：页面卸载前立即执行置顶操作。使用 addEventListener('beforeunload', () => window.scrollTo(0, 0))，而非 onbeforeunload = ...（后者易被覆盖）。这样做用户几乎看不到任何跳动。
• pageshow：捕获浏览器缓存恢复场景（如 iOS 的后退，或 Android 系统回收后重建页面）。当 e.persisted === true 时，再执行一次 window.scrollTo(0, 0)。

两个事件缺一不可：beforeunload 无法拦截缓存页的恢复，pageshow 无法拦截普通刷新。

示例代码如下：

if ('scrollRestoration' in window.history) {
  window.history.scrollRestoration = 'manual';
}

window.addEventListener('beforeunload', () => {
  window.scrollTo(0, 0);
});

window.addEventListener('pageshow', (e) => {
  if (e.persisted) {
    window.scrollTo(0, 0);
  }
});

特别关注：虚拟列表场景的坑

若使用 react-window 或 vue-virtual-scroller 等虚拟滚动方案，情况更复杂。它们常配合 body { overflow: hidden } 或 overflow-y: hidden 等布局 hack 工作。此种布局下，即使设置了 scrollRestoration = 'manual'，刷新后浏览器仍可能将旧的 scrollY 值强行应用到一个“不可滚动”的 body 上，导致内容截断、顶部留白或底部消失等视觉异常。

• 时机至关重要：beforeunload 中的 scrollTo(0, 0) 必须在 DOM 卸载前执行，而非依赖 DOMContentLoaded 或 load 事件（触发太晚，用户会看到跳变）。
• 避免在生命周期钩子中置顶：不要在 useEffect 或 mounted 钩子中做置顶操作——那是在新页面渲染完成后才执行，必然闪动。
• 检查布局干扰：若使用 position: fixed + top: 0 的全屏容器，需检查是否意外继承了父级的 transform 或 will-change 属性，这些可能干扰滚动坐标计算。

总体而言，最稳妥的路径是：设置 scrollRestoration = 'manual' + beforeunload 置顶 + pageshow 补漏。任何其他时机的 scrollTo 都只是妥协方案，容易在慢设备或特定 iOS 版本上出现问题。这才是从根源解决问题的思路。