自建React npm包外部引用时Less样式未加载问题

核心问题原因 #

• 组件库使用了普通前端应用的webpack打包配置，没有按类库模式编译导出资源，Less文件既没有被编译进最终产物，package.json也没有声明样式入口，外部项目安装后无法读取到样式资源
• Less loader配置顺序错误，webpack loader按从右到左/从下到上的顺序执行，现有配置重复声明less-loader且执行顺序完全颠倒，无法正常编译Less语法
• 宿主项目webpack默认会排除node_modules目录下的所有文件做loader编译，组件包存放在node_modules中时，内部的Less源码不会被宿主项目的构建工具处理
• 包配置存在基础错误：package.json中"private": true字段会阻止包发布到公共npm源，且name字段与实际发布的@linkne/react-storybook-antdesign不一致，未配置main/module入口字段，会导致资源解析异常

分步修复方案 #

1. 重构组件库打包配置（推荐使用Rollup，React组件库通用方案） #

安装必要打包依赖：

npm i -D rollup @rollup/plugin-node-resolve @rollup/plugin-babel rollup-plugin-less rollup-plugin-postcss cssnano

在组件库根目录新建rollup.config.js配置文件：

import babel from '@rollup/plugin-babel';
import resolve from '@rollup/plugin-node-resolve';
import less from 'rollup-plugin-less';
import postcss from 'rollup-plugin-postcss';

export default {
  input: './components/App.js',
  output: [
    {
      file: 'dist/index.cjs.js',
      format: 'cjs',
      exports: 'named'
    },
    {
      file: 'dist/index.esm.js',
      format: 'esm'
    }
  ],
  external: ['react', 'react-dom', 'antd'],
  plugins: [
    resolve(),
    babel({
      exclude: 'node_modules/**',
      presets: ['@babel/preset-react'],
      babelHelpers: 'bundled'
    }),
    less({
      output: 'dist/style.css',
      javascriptEnabled: true
    }),
    postcss({
      minimize: true
    })
  ]
}

如果坚持使用webpack打包，需要先安装mini-css-extract-plugin依赖，修正Less loader顺序，替换style-loader为抽离插件，将样式输出为独立CSS文件，避免和宿主项目样式注入逻辑冲突：

const MiniCssExtractPlugin = require('mini-css-extract-plugin');
module.exports = {
  // 入口、输出配置调整为类库模式
  output: {
    path: path.resolve(__dirname, './dist'),
    filename: 'index.js',
    libraryTarget: 'commonjs2'
  },
  // 其余配置不变，插件数组中添加 new MiniCssExtractPlugin()
  module: {
    rules: [
      // js/jsx规则保留
      {
        test: /\.less$/,
        use: [
          MiniCssExtractPlugin.loader,
          'css-loader',
          'postcss-loader',
          {
            loader: 'less-loader',
            options: {
              lessOptions: {
                javascriptEnabled: true
              }
            }
          }
        ]
      }
    ]
  }
}

2. 修正组件库package.json配置 #

删除"private": true字段，修改name为实际发布的包名，补充入口、文件配置，将框架依赖移到peerDependencies避免重复打包：

{
  "name": "@linkne/react-storybook-antdesign",
  "version": "0.2.9",
  "description": "Storybook design systems with AntDesign",
  "license": "MIT",
  "main": "dist/index.cjs.js",
  "module": "dist/index.esm.js",
  "style": "dist/style.css",
  "files": ["dist"],
  "scripts": {
    "build:lib": "rollup -c",
    // 其余原有脚本保留
  },
  "peerDependencies": {
    "react": ">=17.0.0",
    "react-dom": ">=17.0.0",
    "antd": ">=4.0.0"
  }
  // 其余dependencies、devDependencies配置按需保留
}

3. 宿主项目适配（可选，源码编译场景使用） #

如果不抽离独立CSS文件，需要让宿主项目直接编译node_modules内组件包的Less源码，修改宿主项目webpack的Less规则，放行组件包目录：

{
  test: /\.less$/,
  exclude: /node_modules[\\/](?!@linkne[\\/]react-storybook-antdesign)/,
  use: [
    'style-loader',
    'css-loader',
    'postcss-loader',
    {
      loader: 'less-loader',
      options: {
        lessOptions: {
          javascriptEnabled: true
        }
      }
    }
  ]
}

注意宿主项目使用的less-loader为7.x版本，配置语法与11.x版本存在差异，不要直接抄高版本配置。

4. 验证流程 #

• 在组件库目录执行构建命令，确认dist目录下生成JS产物与style.css文件
• 重新发布npm包，宿主项目安装新版本后，在项目入口引入样式即可：import '@linkne/react-storybook-antdesign/dist/style.css'
• 源码编译场景直接重启宿主项目开发服务即可验证样式效果

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