React Router路由切换过渡后无法自动滚动到页面顶部排查

问题背景 #

需求为站点内页面跳转完成后，页面自动滚动到顶部位置。参考官方滚动恢复指南封装了独立的ScrollToTop组件，代码如下：

import { useEffect } from "react";
import { useLocation } from "react-router-dom";

export default function ScrollToTop() {
  const { pathname } = useLocation();

  useEffect(() => {
    window.scrollTo(0, 0);
  }, [pathname]);

  return null;
}

已尝试操作 #

• 按照文档说明将<ScrollToTop />组件放置在<BrowserRouter />内部、<Switch />组件之前。因项目路由拆分在不同文件，<App />为独立文件，组件未放置在<App />附近
• 控制台调试确认路由变化时组件内逻辑正常触发，但页面无滚动效果
• 尝试过同主题的多个公开解决方案，均未适配生效

待排查疑问 #

• 函数外调用window.scrollTo(0, 0)不生效，是否有可替代的实现方案
• <ScrollToTop />组件的放置位置是否有误，是否必须放在<App />组件附近才能生效

1. 组件位置问题澄清 #

组件不需要强制放在<App />附近，只要满足处于Router上下文内部、路由渲染组件的外层这两个条件即可，你当前放置的位置（BrowserRouter内、Switch前）完全符合要求，位置本身不会导致功能失效。

2. 90%场景的失效根因：滚动容器不是window #

绝大多数这类问题都是因为项目给根节点设置了overflow: auto/scroll、height: 100vh这类样式，实际产生滚动条的是内部DOM节点，而非window对象，此时调用window.scrollTo自然不会生效。
排查方法：打开浏览器控制台，跳转页面前后分别执行window.scrollY，如果值始终为0，即可确认滚动容器不是window。
修复逻辑：直接对实际滚动容器调用滚动方法，同时做兼容兜底：

useEffect(() => {
  // 兼容window作为滚动容器的场景
  window.scrollTo(0, 0);
  // 兼容html/body、自定义根容器作为滚动容器的场景
  document.scrollingElement?.scrollTo(0, 0);
  document.getElementById("root")?.scrollTo(0, 0);
}, [pathname]);

如果你的滚动容器是其他自定义节点，把对应选择器替换掉即可。

3. 次常见失效原因：逻辑执行时机不对 #

如果项目配置了路由切换动画、页面内容为接口异步加载，useEffect触发时新页面的DOM还未渲染完成、页面高度未撑开，此时调用滚动方法只会滚动到旧页面的顶部，等新内容加载完成后页面就会停在中间位置。
这种场景加一个短延时兜底即可：

useEffect(() => {
  const handleScrollTop = () => {
    window.scrollTo(0, 0);
    document.scrollingElement?.scrollTo(0, 0);
  };
  handleScrollTop();
  // 兜底处理异步渲染、路由动画场景，100ms延迟用户无感知
  const timer = setTimeout(handleScrollTop, 100);
  return () => clearTimeout(timer);
}, [pathname]);

4. 疑问解答 #

• 函数外调用window.scrollTo不生效是正常现象：函数外的代码会在组件初始化阶段、路由未发生变化时就执行，此时还未触发页面跳转，自然看不到滚动效果，滚动逻辑必须放在pathname变化的回调（即useEffect）内执行。
• 不需要纠结组件和<App />的位置关系：只要组件能正常通过useLocation获取路由变化信息、逻辑能在pathname更新时触发，位置就不会影响功能。

内容的提问来源于stack exchange，提问作者user19251203