如何借助 history.scrollRestoration 手动控制单页应用在页面刷新后是否保持滚动位置

history.scrollRestoration = 'manual' 会禁用浏览器自动滚动恢复，导致刷新后总回到顶部；真正可行的是用 localStorage 主动存取 window.scrollY，并在 DOM 加载完成、路由就绪后精准恢复。

不能直接用 history.scrollRestoration = 'manual' 实现“刷新后保持滚动位置”——它恰恰是禁用保持的开关。 想在单页应用（SPA）中让页面刷新后回到上次位置，得绕开这个 API 的默认逻辑，自己存、自己取、自己滚。

为什么 history.scrollRestoration = 'manual' 不适合“保持滚动”场景

这个属性只有两个值：'auto'（默认，浏览器自动恢复）和 'manual'（完全不恢复，总从顶部开始）。设成 'manual' 后，浏览器连“记都不记”滚动位置，history.back() 或刷新后都必然回到 0, 0。它解决的是“不想滚到底部”的问题，不是“想滚回原来位置”的问题。

• history.scrollRestoration 是历史状态级控制，只影响浏览器原生的滚动恢复行为，不提供读取或写入位置的能力
• SPA 刷新时整个页面重载，history.state 通常为空，无法从中提取旧 scrollY
• 即使你在跳转前用 history.pushState() 存了位置，刷新后该 state 也不会自动触发恢复逻辑

真正可行的方案：用 localStorage 主动存取 window.scrollY

这是目前最稳定、兼容性最好、SPA 场景下事实标准的做法。关键在于时机和清理逻辑。

• 在用户即将离开当前路由时保存：监听 beforeunload，或更可靠地，在 router.beforeEach（Vue Router） / useEffect 卸载（React Router v6+）中调用 localStorage.setItem('scrollPosition', String(window.scrollY))
• 在新页面加载完成后恢复：在 DOMContentLoaded 或路由组件 mounted/useEffect 中读取 localStorage.getItem('scrollPosition')，并执行 window.scrollTo({ top: parseInt(pos), behavior: 'auto' })
• 务必在恢复后立即 localStorage.removeItem('scrollPosition')，避免跨页面污染（比如从文章页跳到首页，不该把文章页的 scrollY 带过去）
• 移动端注意：beforeunload 在 iOS Safari 中可能被忽略，建议配合 visibilitychange 事件兜底

容易踩的坑：行为不一致、闪动、重复触发

很多实现看似能跑，但上线后出现“先闪到底部再弹回”“点返回键位置错乱”“iOS 上完全不生效”，基本都出在这几处。

• 没加 behavior: 'auto'：Chrome 默认 smooth 滚动会触发两次 layout，导致视觉闪动；SPA 刷新恢复必须用 'auto'
• 恢复时机太早：在 DOM 还没渲染完就 scrollTo，结果滚到一个不存在的 offset；应等 document.readyState === 'complete' 或框架的 onMounted 钩子
• 多个路由共用同一个 key：比如所有页面都用 'scrollPosition'，A 页滚到 1200 去 B 页，B 页刷新后却滚到 1200 —— 应按路由路径生成 key，例如 `scroll-${location.pathname}`
• 没处理 iframe 或第三方组件干扰：某些广告/统计脚本会在 onload 后强行 scrollTo(0,0)，覆盖你的恢复逻辑；可在恢复后加 setTimeout(() => {...}, 100) 错峰执行

真正复杂的点不在存取本身，而在于“什么时候存”和“什么时候取”要和你的路由生命周期严丝合缝。尤其在 SSR 渲染 + hydration 的场景下，服务端没有 window，客户端首次执行时 DOM 可能还没 ready，这些边界条件比 API 调用本身更值得花时间验证。