React Router 6.15 中实现页面跳转时自动滚动到顶部的完整方案

在 React Router 6.15 中，ScrollRestoration 组件可原生支持导航时滚动至顶部及历史回退时恢复滚动位置；若需更精细控制，也可通过自定义 useScrollToTop Hook 或布局级组件实现。

在 React Router 6.15 中，`ScrollRestoration` 组件可原生支持导航时滚动至顶部及历史回退时恢复滚动位置；若需更精细控制，也可通过自定义 `useScrollToTop` Hook 或布局级组件实现。

很多开发者可能没意识到，在 React Router v6.15 里，框架已经内置了相当完善的滚动行为管理能力。这意味着你再也不需要像以前那样，手动封装一个 ScrollToTop 组件了。直接就能实现我们理想中的用户体验：跳转新页面时自动滚动到顶部，而点击浏览器后退按钮时，又能精准地回到之前的阅读位置。具体怎么操作呢？核心方案其实就两种：要么直接用官方的，要么根据需求“自己动手”。

推荐方案：使用 （数据路由专属）

这个 组件，可以看作是 React Router 官方给的“保姆级”工具。不过得注意，它有个使用前提：只适用于数据路由器（比如 createBrowserRouter），而且必须乖乖待在路由的上下文环境里，也就是放在 RouterProvider 内部才行。

它的工作逻辑非常清晰，就干两件事：

• 当用户在应用内进行新的导航（push）时，它会自动将窗口滚动到页面顶部。
• 而当用户点击浏览器的后退或前进按钮（pop）时，它又能非常聪明地恢复到该路由上一次离开时的滚动位置。这背后依赖的是浏览器 history.state 的机制。

使用起来也相当省心。你只需要在根布局组件（比如叫做 Layout）里渲染一次就够了。常规做法是把它放在 的旁边：

// components/Layout.tsx
import { Outlet, ScrollRestoration } from 'react-router-dom';

export default function Layout() {
  return (
    

      
My App
      

        {/* ScrollRestoration 必须在此处渲染 */}
        
        
      
      
    
  );
}

这里有几点需要特别注意：

• 千万别把 ScrollRestoration 直接塞到通过 createRoutesFromElements 定义的 JSX 路由结构里（比如写在某个 标签内部）。因为它本质上是一个UI组件，而非路由配置元素。
• 它的生效依赖于浏览器将 history.scrollRestoration 设置为 ‘manual’。所以，得确保你的项目里没有其他代码把这个设置给覆盖掉。
• 当然，如果默认的滚动整个页面的行为不满足你的需求，比如你只想滚动某个特定容器，官方也预留了自定义的接口，可以通过 getKey 属性来实现更精细的控制（具体可以参考官方文档）。

替代方案：手动控制滚动（适用于特殊场景）

那什么时候需要考虑“自己动手”呢？通常是 无法满足你的特定需求时。比如，你希望所有导航（包括后退）都强制滚动到顶部，完全忽略历史位置恢复；或者你需要滚动到页内某个特定元素，而不仅仅是顶部。这时候，下面两种手动控制的方式就能派上用场了。

方式 1：自定义 Hook（推荐用于逻辑复用）

如果你喜欢逻辑清晰、便于复用的方式，自定义一个 Hook 是个好选择。它的原理是利用 useEffect 监听路由路径的变化。

// hooks/useScrollToTop.ts
import { useEffect } from 'react';
import { useLocation } from 'react-router-dom';

export function useScrollToTop() {
  const { pathname } = useLocation();

  useEffect(() => {
    window.scrollTo({ top: 0, left: 0, beha vior: 'smooth' }); // 可以设置平滑滚动
  }, [pathname]);
}

在需要使用这个功能的布局组件里，直接调用这个 Hook 即可：

// components/Layout.tsx
import { Outlet } from 'react-router-dom';
import { useScrollToTop } from '../hooks/useScrollToTop';

export default function Layout() {
  useScrollToTop(); // 每次 pathname 变化时触发
  return (
    

      ...
      
    
  );
}

方式 2：独立布局路由组件（适合嵌套滚动控制）

另一种思路是创建一个独立的布局组件，专门负责滚动控制。这种方式特别适合在多层嵌套的路由结构中，统一管理某一部分路由的滚动行为。

// layouts/ScrollToTopLayout.tsx
import { useEffect, type ReactNode } from 'react';
import { Outlet, useLocation } from 'react-router-dom';

export default function ScrollToTopLayout({ children }: { children?: ReactNode }) {
  const { pathname } = useLocation();

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

  return <>{children  }>;
}

然后，在你的路由配置中，用它来包裹需要控制滚动的路由组：

// App.tsx
import { createBrowserRouter, createRoutesFromElements, Route, RouterProvider } from 'react-router-dom';
import Layout from './components/Layout';
import Home from './pages/Home';
// ... 其他页面

const router = createBrowserRouter(
  createRoutesFromElements(
    >
      >
        } />
        } />
        } />
        } />
        } />
      
    
  )
);

export default function App() {
  return ;
}

总结与选型建议

说了这么多，到底该选哪个？不妨通过下面这个表格来快速决策：

方案	适用场景	是否恢复历史滚动	是否需额外配置	推荐指数
	标准 SPA 导航体验（含前进/后退）	是	否（开箱即用）
useScrollToTop Hook	简单“始终滚顶”，逻辑需复用	否	否
布局组件（ScrollToTopLayout）	需多层嵌套路由统一控制	否	否

简单来说， 是 React Router 官方力推的现代解决方案，兼容性好、语义清晰，而且几乎没有副作用。除非你有非常明确的理由，比如需要兼容特殊的服务端渲染场景，或者需要定制非 window 的滚动容器，否则，它就是你的首选。