Solutions for Global CSS Not Loading from Component Library in Next.js

我太懂这种摸不着头脑的感觉了——明明组件库的配置看起来都对，结果全局样式偏要等个console.log(components)才肯加载，简直像故意闹脾气！这种情况十有八九是Tree Shaking在搞鬼：Next.js（尤其是App Router模式下）的优化机制会把它认为“没用”的代码（包括关联的样式）给摇掉，而你那行console.log刚好让整个components对象被标记为“有用”，连带把全局样式也保留下来了。

下面给你几个实用的解决方案，按从易到难、从临时到根治的顺序排列：

1. 显式导入全局样式（最快验证方案） #

既然隐式加载靠不住，那就直接在你的客户端组件里手动导入组件库的全局样式文件。比如：

"use client";
import { FloButton } from 'component-library';
// 显式导入组件库的全局样式，路径根据实际打包后的文件调整
import 'component-library/dist/main.css'; 

export default function Home() {
  return (
    <>
      <FloButton click={() => console.log('clicked')}>Button</FloButton>
    </>
  );
}

这个方法的好处是立竿见影，不需要改组件库的配置，适合快速验证问题根源。

2. 修复组件库的sideEffects配置（根治Tree Shaking问题） #

你的组件库用了vite-plugin-css-injected-by-js，这个插件会把CSS转换成JS代码动态注入到页面中。但目前你的package.json里只把CSS/SCSS文件标记为sideEffect，转换后的JS文件（比如dist/main.js）里的样式注入代码没被标记为sideEffect，导致Next.js的Tree Shaking把这部分“无用”代码删掉了。

修改组件库的package.json，把打包后的JS主文件也加入sideEffects数组：

"sideEffects": [
  "**/*.css",
  "**/*.scss",
  "dist/main.js",
  "dist/webcomponents.js"
]

这样Next.js就会知道这些JS文件包含需要保留的副作用（比如样式注入），不会把它们摇掉，全局样式就能正常加载了。

3. 模块化样式导入（更优雅的长期方案） #

如果你的组件库是按组件拆分样式的，建议把每个组件的样式和组件本身绑定——也就是在每个组件的入口文件里直接导入对应的样式，而不是依赖全局导入。比如在FloButton.jsx里：

// FloButton.jsx
import './FloButton.scss'; // 导入组件专属样式
export const FloButton = () => { /* 组件代码 */ };

这样当你导入FloButton时，对应的样式会自动被引入，Tree Shaking也不会碰它（因为组件代码依赖了这个导入）。这种方式更符合模块化的理念，也能避免全局样式的冲突问题。

4. 调整Next.js的Webpack配置（兜底方案） #

如果上面的方法都不管用，你可以直接在Next.js的配置里强制保留组件库的sideEffect代码。在next.config.js里添加：

export default {
  webpack: (config) => {
    // 告诉Webpack，component-library的所有文件都包含sideEffect
    config.module.rules.push({
      test: /\.(js|css|scss)$/,
      include: /node_modules\/component-library/,
      sideEffects: true,
    });
    return config;
  },
};

这个配置会让Webpack跳过对组件库文件的Tree Shaking，确保所有副作用代码（包括样式）都被保留。

最后给你个优先级建议：先试方案1验证问题，然后用方案2根治，方案3作为长期架构优化方向，方案4留作兜底。

内容来源于stack exchange