解决Next.js 13自定义主题应用时的页面闪烁问题

核心原因 #

页面重载时默认浅色主题先于自定义主题加载，本质是客户端动态创建样式的时机滞后于页面初始渲染，导致短暂的样式切换闪烁。

具体解决方案 #

• 服务端预渲染注入主题样式
  在页面的服务端数据获取方法（getServerSideProps 或 generateStaticParams+generateStaticProps）中先拿到对应slug的主题数据，然后在_document.tsx（Pages Router）或根布局（App Router）中直接将主题变量编译成内联样式注入到<head>里。这样页面首次渲染时就自带自定义主题样式，不会出现默认主题的闪烁。
  示例代码（Pages Router）：

  // pages/[slug].tsx
  export async function getServerSideProps(context) {
    const { slug } = context.params;
    // 替换为实际数据库查询逻辑，测试阶段可硬编码
    const theme = { primary: '#ff0000', secondary: '#00ff00' };
    return { props: { theme } };
  }
  
  // _document.tsx
  import Document, { Html, Head, Main, NextScript } from 'next/document';
  
  class MyDocument extends Document {
    static async getInitialProps(ctx) {
      const initialProps = await Document.getInitialProps(ctx);
      const theme = ctx?.renderPage?.props?.theme || {};
      return { ...initialProps, theme };
    }
  
    render() {
      const { theme } = this.props;
      return (
        <Html>
          <Head>
            <style
              data-theme="custom"
              dangerouslySetInnerHTML={{
                __html: `
                  :root[data-theme="custom"] {
                    --primary-color: ${theme.primary};
                    --secondary-color: ${theme.secondary};
                  }
                `,
              }}
            />
          </Head>
          <body>
            <Main />
            <NextScript />
          </body>
        </Html>
      );
    }
  }
  
  export default MyDocument;
  

• 屏蔽默认主题的初始生效
  修改全局样式，让默认浅色主题仅在没有自定义主题时生效：

  /* 全局样式文件 */
  :root[data-theme="default"] {
    /* 默认浅色主题变量 */
    --primary-color: #ffffff;
    --secondary-color: #000000;
  }
  
  :root[data-theme="custom"] {
    /* 自定义主题变量会覆盖默认 */
  }
  

  同时确保根元素初始时不设置data-theme="default"，或在服务端渲染时直接设置data-theme="custom"，避免默认样式先触发。

• App Router场景下的优化
  如果使用App Router，直接在Server Component的根布局中获取主题数据并渲染内联样式：

  // app/[slug]/layout.tsx
  export default async function Layout({ params, children }) {
    const { slug } = params;
    const theme = await fetchThemeFromDB(slug); // 数据库查询逻辑
    return (
      <html data-theme="custom">
        <head>
          <style
            dangerouslySetInnerHTML={{
              __html: `
                :root {
                  --primary-color: ${theme.primary};
                  --secondary-color: ${theme.secondary};
                }
              `,
            }}
          />
        </head>
        <body>{children}</body>
      </html>
    );
  }
  

关键思路 #

让自定义主题样式在页面初始渲染阶段就存在，而不是等客户端React hydration完成后再动态创建，从根源上避免样式切换的闪烁。

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