react-router-dom ScrollRestoration失效求助：页面跳转后始终回到顶部

核心排查与修复方案 #

1. 确认ScrollRestoration的正确放置位置 #

必须将<ScrollRestoration />放在共享布局组件的<Outlet />同级位置（也就是你的AppLayout组件内），确保所有子路由都能继承滚动恢复逻辑。错误放置在RouterProvider或单独子路由中都会导致失效。示例代码：

function AppLayout() {
  return (
    <div className="vertical-layout">
      <header>顶部导航</header>
      <main>
        <Outlet />
        <ScrollRestoration /> {/* 与Outlet同层级，放在main容器内 */}
      </main>
      <footer>底部区域</footer>
    </div>
  );
}

2. 适配自定义滚动容器（垂直三分布局的关键） #

垂直三分布局下，滚动行为通常不是在window上，而是在自定义容器（比如main标签）内。React Router默认的ScrollRestoration仅监听window滚动，此时需要自定义滚动恢复逻辑：

import { useLocation, Outlet } from 'react-router-dom';
import { useEffect, useRef } from 'react';

function AppLayout() {
  const location = useLocation();
  const scrollContainerRef = useRef(null);
  // 用ref存储各路由的滚动位置，也可改用sessionStorage持久化
  const scrollPositionsRef = useRef({});

  // 监听滚动，保存当前位置
  useEffect(() => {
    const container = scrollContainerRef.current;
    if (!container) return;

    const saveScrollPos = () => {
      scrollPositionsRef.current[location.pathname] = container.scrollTop;
    };
    container.addEventListener('scroll', saveScrollPos);
    return () => container.removeEventListener('scroll', saveScrollPos);
  }, [location.pathname]);

  // 路由切换时恢复滚动位置
  useEffect(() => {
    const container = scrollContainerRef.current;
    if (!container) return;

    const savedPos = scrollPositionsRef.current[location.pathname] || 0;
    // 用requestAnimationFrame确保DOM更新后再执行滚动
    requestAnimationFrame(() => {
      container.scrollTop = savedPos;
    });
  }, [location.pathname]);

  return (
    <div className="vertical-layout">
      <header>顶部导航</header>
      {/* 给滚动容器设置固定高度和overflow属性 */}
      <main 
        ref={scrollContainerRef} 
        style={{ overflowY: 'auto', height: 'calc(100vh - 120px)' }}
      >
        <Outlet />
      </main>
      <footer>底部区域</footer>
    </div>
  );
}

3. 排查并禁用默认滚动重置行为 #

检查项目中是否存在全局的window.scrollTo(0, 0)调用，或路由跳转时的自定义逻辑强制重置滚动位置，这类代码会覆盖ScrollRestoration的行为。

4. 确认路由配置结构 #

确保AppLayout作为父路由的element，所有需要滚动恢复的子路由都嵌套在其下：

const router = createBrowserRouter([
  {
    path: '/',
    element: <AppLayout />,
    children: [
      { path: '', element: <Home /> },
      { path: 'posts/:id', element: <PostDetail /> },
      // 其他子路由
    ],
  },
]);

额外注意事项 #

• 若开启React.StrictMode导致useEffect触发两次，可改用sessionStorage存储滚动位置，避免数据丢失：

  // 保存位置
  sessionStorage.setItem(`scroll_${location.pathname}`, container.scrollTop.toString());
  // 恢复位置
  const savedPos = parseInt(sessionStorage.getItem(`scroll_${location.pathname}`)) || 0;
  

• 确保滚动容器的高度是固定值（如calc(100vh - 头部高度 - 底部高度)），否则容器高度变化会导致滚动位置计算错误。

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