Rollup构建的React组件库在Next.js SSR中CSS加载异常问题

你的问题核心是当前Rollup配置里的postcss插件默认处理方式导致CSS无法在Next.js SSR阶段同步注入页面——要么生成了单独的CSS文件需客户端加载，要么是客户端动态注入样式，最终出现组件先渲染、样式后加载的情况。

推荐解决方案：将CSS内联到组件JS中（SSR友好） #

修改Rollup的postcss插件配置，让样式直接嵌入组件代码，这样Next.js在服务端渲染时就能收集这些样式并输出到HTML的style标签里，实现样式与组件同步加载。

修改你的rollup.config.mjs中postcss部分的配置：

postcss({
  // 启用CSS Modules（可选，若组件使用了模块化样式则开启）
  modules: {
    generateScopedName: "[name]__[local]___[hash:base64:5]",
  },
  // 禁止单独提取CSS文件，将样式内联到JS模块中
  extract: false,
  // 自动将样式注入到页面head的style标签，Next.js SSR会识别并处理
  inject: true,
  // 可选：添加autoprefixer等CSS后处理插件
  plugins: [require('autoprefixer')],
})

同时确保组件文件里直接导入对应的CSS：

// 示例组件文件
import './Button.css';

const Button = () => (
  <button className="btn">点击按钮</button>
);

export default Button;

备选方案：全局导入组件包CSS #

如果希望保留单独的CSS文件，可在Next.js的根布局或_app文件中全局导入组件包的CSS文件：

// App Router 下的 app/layout.tsx
import 'your-component-package/dist/cjs/index.css'; // 替换为你组件包实际的CSS路径

export default function RootLayout({ children }) {
  return (
    <html lang="zh-CN">
      <body>{children}</body>
    </html>
  );
}

这种方式的缺点是CSS会全量注入页面，不管组件是否被使用，灵活性不如内联方案。

额外配置检查 #

1. 确保TypeScript允许导入CSS文件，在tsconfig.json中添加相关配置：

{
  "compilerOptions": {
    "moduleResolution": "node",
    "allowSyntheticDefaultImports": true,
    "esModuleInterop": true,
    "types": ["node"]
  },
  "include": ["src/**/*"]
}

2. 你的dts配置中external: [/\.css$/]是正确的，类型定义不需要包含CSS文件。

完成上述修改后，重新打包组件包并更新Next.js项目中的依赖，启动项目后查看SSR生成的HTML源码，就能看到组件的CSS已经包含在head的style标签中，不会再出现样式延迟加载的问题。

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