如何避免Next.js静态导出时styled-components未加载前渲染组件UI

针对你在同一仓库下使用自定义styled-components组件库，Next.js静态导出后样式未在初始渲染加载的问题，可通过以下步骤解决：

1. 配置Next.js的styled-components静态导出支持 #

Next.js静态导出需要在构建阶段将styled-components的样式注入到生成的HTML中，需完成两处配置：

配置next.config.js #

启用styled-components编译器，并指定静态导出模式：

// next.config.js
module.exports = {
  compiler: {
    styledComponents: true,
  },
  output: 'export',
}

自定义_document.js收集样式 #

创建pages/_document.js，通过ServerStyleSheet收集所有styled-components的样式，并注入到HTML的<head>中：

// pages/_document.js
import Document, { Html, Head, Main, NextScript } from 'next/document'
import { ServerStyleSheet } from 'styled-components'

export default class MyDocument extends Document {
  static async getInitialProps(ctx) {
    const sheet = new ServerStyleSheet()
    const originalRenderPage = ctx.renderPage

    try {
      ctx.renderPage = () =>
        originalRenderPage({
          enhanceApp: (App) => (props) => sheet.collectStyles(<App {...props} />),
        })

      const initialProps = await Document.getInitialProps(ctx)
      return {
        ...initialProps,
        styles: (
          <>
            {initialProps.styles}
            {sheet.getStyleElement()}
          </>
        ),
      }
    } finally {
      sheet.seal()
    }
  }

  render() {
    return (
      <Html>
        <Head />
        <body>
          <Main />
          <NextScript />
        </body>
      </Html>
    )
  }
}

2. 优化组件库的styled-components写法 #

确保组件库中的样式定义在组件外部（顶层作用域），避免在组件函数内部动态创建styled组件——这种写法会导致静态导出时无法收集样式：

正确写法 #

// 组件库中的Button组件
import styled from 'styled-components'

// 样式定义在组件外部
const StyledButton = styled.button`
  padding: 8px 16px;
  border-radius: 4px;
  background-color: #0070f3;
  color: white;
  border: none;
  cursor: pointer;
`

export const Button = ({ children }) => {
  return <StyledButton>{children}</StyledButton>
}

错误写法（需避免） #

// 错误：在组件内部动态创建样式，无法被静态收集
export const Button = ({ children }) => {
  const StyledButton = styled.button`
    padding: 8px 16px;
    background-color: #0070f3;
  `
  return <StyledButton>{children}</StyledButton>
}

3. 添加兜底方案：样式加载前隐藏UI #

若上述配置仍有边缘情况（如CDN缓存导致样式加载延迟），可在页面或根组件中添加加载判断，直到styled-components样式加载完成后再渲染UI：

import { useState, useEffect } from 'react'
import { Button } from '@your-component-library'

export default function HomePage() {
  const [isStylesReady, setIsStylesReady] = useState(false)

  useEffect(() => {
    const checkStyledStyles = () => {
      // 检查是否存在styled-components生成的样式标签
      const styledTags = document.querySelectorAll('style[data-styled]')
      if (styledTags.length > 0) {
        setIsStylesReady(true)
      }
    }

    // 初始检查
    checkStyledStyles()
    // 监听head标签的变化，确保样式加载后更新状态
    const observer = new MutationObserver(checkStyledStyles)
    observer.observe(document.head, { childList: true })

    return () => observer.disconnect()
  }, [])

  // 样式未加载时显示骨架屏或加载提示
  if (!isStylesReady) {
    return (
      <div style={{ width: '100vw', height: '100vh', display: 'flex', alignItems: 'center', justifyContent: 'center' }}>
        <div>Loading...</div>
      </div>
    )
  }

  return (
    <div style={{ padding: '24px' }}>
      <Button>测试按钮</Button>
    </div>
  )
}

4. 验证静态导出结果 #

执行next build && next export后，打开生成的out目录下的HTML文件，检查<head>中是否包含带有data-styled属性的<style>标签——这说明样式已成功注入。

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