使用StaticSiteGeneratorPlugin静态渲染时Styled Components提取CSS为空问题

问题排查与解决方案 #

该问题90%以上的场景是Styled Components实例重复导致的，也就是你的外部组件库和主项目各自使用了独立的Styled Components运行时实例，主项目的ServerStyleSheet无法收集到组件库内生成的样式。你可以按以下优先级依次排查：

第一步：定位问题来源 #

先在当前页面模板内直接定义Styled组件做测试，判断是主项目配置问题还是外部组件库问题：

const React = require('react');
const styled = require('styled-components').default;
const { Button }  = require("component-library");

// 新增本地测试组件
const TestBtn = styled.button`
  background: #f00;
  padding: 10px;
`;

const Index = () => {
  return (
      <html>
        <head>
          <title></title>
        </head>
        <body>
          <TestBtn>本地测试按钮</TestBtn>
          <Button>THIS IS RENDERED BY REACT </Button>
        </body>
      </html>
  )
};

module.exports = Index;

重新执行渲染后查看打印的css变量：

• 如果能收集到TestBtn的样式，说明问题出在外部组件库，直接走第二步组件库配置修复
• 如果还是收集不到任何样式，说明是主项目本身的配置问题，走第三步主项目配置修复

第二步：修复组件库配置 #

1. 将Styled Components设为外部依赖
   在组件库的打包配置（Rollup/Webpack）中排除Styled Components，让组件库调用主项目的Styled Components实例：

• 若用Rollup打包，在rollup.config.js中添加：

  export default {
    // 其他配置
    external: ['react', 'react-dom', 'styled-components']
  }
  

• 若用Webpack打包，在webpack.config.js中添加：

  module.exports = {
    // 其他配置
    externals: {
      'styled-components': 'styled-components'
    }
  }
  

2. 调整组件库依赖声明
   在组件库的package.json中，把styled-components从dependencies移到peerDependencies，避免安装时重复下载：

{
  "peerDependencies": {
    "react": ">=16.8.0",
    "styled-components": ">=5.0.0"
  }
}

3. 统一版本号
   确保组件库和主项目使用的Styled Components版本完全一致，避免跨版本兼容问题。

第三步：修复主项目配置 #

如果第一步测试本地样式也无法收集，检查主项目的以下配置：

1. 检查Styled Components Babel插件配置
   确保已经安装babel-plugin-styled-components，且Babel配置中开启了SSR支持：

{
  "plugins": [
    ["styled-components", { "ssr": true }]
  ]
}

2. 版本兼容检查
   确认当前React版本和Styled Components版本兼容：React 18建议使用Styled Components v5.3.10+ 或 v6.x版本。
3. 检查依赖重复
   执行npm ls styled-components 或 pnpm list styled-components 查看项目中是否存在多份Styled Components安装包，若存在手动做依赖提升处理。

额外注意 #

拿到提取到的css变量后，需要手动将其插入到最终输出HTML的<head>标签内，样式才会生效。

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