将UMD组件库导入ESM项目时CSS无法加载的问题

我用Webpack（搭配Babel）将React组件库编译为UMD格式，组件在本地Storybook里加载正常，但导入到新的create-react-app项目时，样式完全失效，类名也不生效。构建后的JS文件里能看到CSS代码和类名，但检查DOM时元素显示为：

<h1 class>Hello World!</h1>

相关文件内容如下：

Library/webpack.config #

module.exports = {
    entry: {
        HelloWorld: './src/components/HelloWorld/index.js',
    },
    externals: {
        'react': 'react',
        'react-dom': 'react-dom',
    },
    mode: 'production',
    module: {
        rules: [
            {
                test: /\.js$/,
                exclude: /node_modules/,
                use: {
                    loader: 'babel-loader',
                    options: {
                        presets: [
                            '@babel/preset-env',
                            [
                                '@babel/preset-react',
                                {
                                    runtime: 'automatic',
                                },
                            ],
                        ],
                    },
                },
            },
            {
                test: /\.module.css$/,
                exclude: /node_modules/,
                use: [
                    {
                        loader: 'style-loader',
                    },
                    {
                        loader: 'css-loader',
                        options: {
                            modules: true,
                        },
                    },
                ],
            },
            {
                test: /\.(png|jpg)$/,
                exclude: /node_modules/,
                loader: 'file-loader',
                options: {
                    outputPath: (url, resourcePath, context) => {
                        const componentName = resourcePath.replace(context, '').split('/')[3];

                        return `${componentName}/${url}`;
                    },
                },
            },
            {
                test: /\.svg$/,
                exclude: /node_modules/,
                loader: '@svgr/webpack',
                options: {
                    exportType: 'named',
                },
            }
        ],
    },
    output: {
        filename: '[name]/index.js',
        library: {
            type: 'umd',
        },
        path: `${__dirname}/build`,
    },
};

Library/package.json #

{
    ...
    "exports": {
        "./HelloWorld": "./build/HelloWorld/index.js"
    }
    ...
  },
}

Library/src/components/HelloWorld/index.js #

import styles from './HelloWorld.module.css';

export default function HelloWorld() {
    return (
        <h1 className={styles.helloWorld}>Hello World!</h1>
    )
}

Library/src/components/HelloWorld/HelloWorld.module.css #

.helloWorld {
    color: red;
}

Project/src/App/index.js #

import HelloWorld from 'my-library/HelloWorld';

export default function App() {
    return (
        <HelloWorld /> 
    )
}

核心问题是生产环境构建UMD组件库时，使用style-loader会导致样式注入异常，甚至css modules的类名导出失效。正确的做法是将CSS抽离为单独文件，让用户手动引入，具体步骤如下：

1. 安装依赖 #

安装mini-css-extract-plugin，用于将CSS从JS中抽离为单独文件：

npm install mini-css-extract-plugin --save-dev

2. 修改Webpack配置 #

替换style-loader为MiniCssExtractPlugin.loader，并添加插件配置：

const MiniCssExtractPlugin = require('mini-css-extract-plugin');

module.exports = {
    entry: {
        HelloWorld: './src/components/HelloWorld/index.js',
    },
    externals: {
        'react': 'react',
        'react-dom': 'react-dom',
    },
    mode: 'production',
    module: {
        rules: [
            // JS处理规则不变
            {
                test: /\.js$/,
                exclude: /node_modules/,
                use: {
                    loader: 'babel-loader',
                    options: {
                        presets: [
                            '@babel/preset-env',
                            [
                                '@babel/preset-react',
                                {
                                    runtime: 'automatic',
                                },
                            ],
                        ],
                    },
                },
            },
            // 更新CSS处理规则
            {
                test: /\.module.css$/,
                exclude: /node_modules/,
                use: [
                    MiniCssExtractPlugin.loader, // 替换style-loader
                    {
                        loader: 'css-loader',
                        options: {
                            modules: {
                                localIdentName: '[hash:base64:8]', // 明确类名生成规则，避免空值
                            },
                        },
                    },
                ],
            },
            // 其他资源处理规则不变
            {
                test: /\.(png|jpg)$/,
                exclude: /node_modules/,
                loader: 'file-loader',
                options: {
                    outputPath: (url, resourcePath, context) => {
                        const componentName = resourcePath.replace(context, '').split('/')[3];

                        return `${componentName}/${url}`;
                    },
                },
            },
            {
                test: /\.svg$/,
                exclude: /node_modules/,
                loader: '@svgr/webpack',
                options: {
                    exportType: 'named',
                },
            }
        ],
    },
    output: {
        filename: '[name]/index.js',
        library: {
            type: 'umd',
        },
        path: `${__dirname}/build`,
    },
    // 添加插件配置
    plugins: [
        new MiniCssExtractPlugin({
            filename: '[name]/index.css', // CSS文件和JS同目录输出
        }),
    ],
};

3. 更新package.json的exports字段 #

添加CSS文件的导出路径，方便用户引入：

{
    ...
    "exports": {
        "./HelloWorld": "./build/HelloWorld/index.js",
        "./HelloWorld/style": "./build/HelloWorld/index.css"
    }
    ...
}

4. 在CRA项目中引入样式 #

用户需要同时导入组件和对应的样式文件：

import HelloWorld from 'my-library/HelloWorld';
import 'my-library/HelloWorld/style';

export default function App() {
    return (
        <HelloWorld /> 
    )
}

为什么之前的配置失效？ #

style-loader是在浏览器运行时将CSS动态插入到<style>标签中，但UMD模块在create-react-app的环境中，可能因为模块加载的沙箱机制导致样式注入失败；同时生产环境下Webpack的优化可能会干扰css modules的导出逻辑，导致类名变为空值。抽离CSS为单独文件是组件库打包的标准方案，能避免这类兼容性问题，同时让用户更好地控制样式的加载和覆盖。

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