GatsbyJS中如何正确使用OverlayScrollbars组件替换默认滚动条

想把Gatsby网站的默认滚动条替换成OverlayScrollbars组件，解决页面导航时因滚动条有无导致的页面轻微左移问题。尝试使用overlayscrollbars-react包，但找不到正确的组件放置位置：

• 在src/html.js中包裹<html>标签导致页面空白
• 包裹<body>标签或在index.tsx等文件中包裹其他元素无效
• 当前已在PageBase.tsx中引入组件，但仍显示默认滚动条

用户提供的代码如下：

index.tsx #

import * as React from "react";
import PageBase from "./PageBase";

export default function Home() {
    const navigation = [
        { name: "Home", href: "/", current: true },
        { name: "About", href: "/About/", current: false },
        { name: "My Work", href: "/My-Work", current: false },
        { name: "Contact Me", href: "/Contact", current: false },
    ];

    return (
        <>
            <PageBase navigation={navigation}>
                <p>example content</p>
            </PageBase>
        </>
    );
}

PageBase.tsx #

import * as React from "react";
import NavBar from "../components/nav";
import Footer from "../components/footer";
import { OverlayScrollbarsComponent } from "overlayscrollbars-react";
import "overlayscrollbars/css/OverlayScrollbars.css";


export default function PageBase(props: any) {
    return (
        <>
            <OverlayScrollbarsComponent>
                <div className="flex flex-col dark:bg-zinc-800 min-h-screen">
                    <NavBar navigation={props.navigation}></NavBar>

                    <main className="flex justify-center mt-5 flex-grow overflow-hidden">
                        <div className="w-5/6 lg:w-4/6">
                            {props.children}
                            <br />
                            <br />
                        </div>
                    </main>

                    <Footer />
                </div>
            </OverlayScrollbarsComponent>   
        </>
    );
}

要在Gatsby中全局替换滚动条，需利用Gatsby的wrapRootElement API全局注入OverlayScrollbars，同时配合CSS隐藏原生滚动条，具体步骤如下：

步骤1: 创建全局滚动包裹组件 #

在src/components/GlobalScrollWrapper.tsx中新建全局滚动容器：

import * as React from "react";
import { OverlayScrollbarsComponent } from "overlayscrollbars-react";
import "overlayscrollbars/css/OverlayScrollbars.css";

const GlobalScrollWrapper = ({ children }: { children: React.ReactNode }) => {
  // 配置滚动条参数，可根据需求调整
  const osOptions = {
    scrollbars: {
      autoHide: "never",
      theme: "os-theme-dark", // 匹配你的网站主题，也可自定义
    },
  };

  return (
    <OverlayScrollbarsComponent
      options={osOptions}
      style={{ height: "100vh", width: "100vw", overflow: "auto" }}
    >
      {children}
    </OverlayScrollbarsComponent>
  );
};

export default GlobalScrollWrapper;

步骤2: 配置Gatsby全局包裹逻辑 #

在项目根目录新建或修改gatsby-browser.js：

import * as React from "react";
import GlobalScrollWrapper from "./src/components/GlobalScrollWrapper";

export const wrapRootElement = ({ element }) => {
  return <GlobalScrollWrapper>{element}</GlobalScrollWrapper>;
};

同时新建或修改gatsby-ssr.js（保证SSR渲染一致性）：

import * as React from "react";
import GlobalScrollWrapper from "./src/components/GlobalScrollWrapper";

export const wrapRootElement = ({ element }) => {
  return <GlobalScrollWrapper>{element}</GlobalScrollWrapper>;
};

步骤3: 隐藏原生滚动条 #

在全局CSS文件（比如src/styles/global.css）中添加样式，彻底禁用原生滚动条：

body {
  overflow: hidden;
}

/* 强制OverlayScrollbars容器占满视口 */
.os-host {
  width: 100vw !important;
  height: 100vh !important;
}

步骤4: 清理原有代码 #

移除PageBase.tsx中的OverlayScrollbarsComponent，避免嵌套冲突：

import * as React from "react";
import NavBar from "../components/nav";
import Footer from "../components/footer";

export default function PageBase(props: any) {
    return (
        <div className="flex flex-col dark:bg-zinc-800 min-h-screen">
            <NavBar navigation={props.navigation}></NavBar>

            <main className="flex justify-center mt-5 flex-grow">
                <div className="w-5/6 lg:w-4/6">
                    {props.children}
                    <br />
                    <br />
                </div>
            </main>

            <Footer />
        </div>
    );
}

关键注意点 #

• 不要直接在src/html.js中包裹<html>或<body>，Gatsby的SSR渲染机制会引发冲突，导致页面空白。
• wrapRootElement能确保整个应用内容被OverlayScrollbars包裹，实现全局滚动条替换。
• 必须同时配置gatsby-browser.js和gatsby-ssr.js，否则开发与生产环境渲染会不一致。

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