Webpack5构建React UMD组件库SourceMap失效与CRA引入报错咨询

原因 #

Production模式下Webpack默认启用的Terser压缩插件未开启SourceMap支持，会默认移除代码末尾的SourceMap关联注释，即使配置了inline-source-map也会导致浏览器无法识别映射关系。

解决方案 #

• 安装terser-webpack-plugin，显式配置压缩插件开启SourceMap支持，修改Webpack.config.js添加如下配置：

const TerserPlugin = require('terser-webpack-plugin');

module.exports = {
  // 保留原有其他配置
  devtool: 'source-map', // 推荐生产环境用独立的map文件，比inline-source-map体积更小
  optimization: {
    minimizer: [
      new TerserPlugin({
        sourceMap: true
      })
    ]
  }
}

• 检查项目根目录的.npmignore文件，不要排除dist/*.map文件，确保发布NPM时SourceMap文件一起上传。
• 若坚持使用inline-source-map，需在Terser配置中添加保留SourceMap注释的规则：

new TerserPlugin({
  sourceMap: true,
  terserOptions: {
    format: {
      comments: /sourceMappingURL/i
    }
  }
})

原因 #

你遇到的所有报错均为CRA内置ESLint的检查报错，而非代码运行错误：

1. UMD格式代码内置了AMD规范的define语法、全局环境判断的self变量，CRA的默认ESLint规则未适配UMD语法，因此抛出未定义、禁用全局变量的错误。
2. 你直接将编译后的产物放在CRA的src目录下，CRA会对src目录下所有JS文件做ESLint检查，不会区分是源码还是已编译的库文件。
3. 现有配置存在两处错误加剧了兼容问题：package.json的main字段指向错误，Webpack配置误用了Node环境专用的外置依赖规则。

解决方案 #

• 优先采用标准的本地测试流程，避免直接将编译产物放入CRA的src目录：
  1. 在组件库根目录执行npm link
  2. 在测试用CRA项目根目录执行npm link test-lib
  3. 直接通过import { Button } from 'test-lib'引入组件，CRA不会对node_modules下的文件做ESLint检查，可避开所有报错
• 修正组件库配置：
  1. 修改package.json的main字段为"main": "dist/index.js"，确保包入口指向正确的构建产物
  2. 将react、react-dom从dependencies移到peerDependencies中，避免用户项目出现重复的React实例
  3. 替换Webpack配置中错误的外置依赖规则，删除externals: [nodeExternals()]，替换为仅外置React相关依赖，同时添加UMD兼容配置：

  module.exports = {
    // 保留原有其他配置
    output: {
      filename: "index.js",
      path: path.resolve(__dirname, "dist"),
      library: {
        name: "test",
        type: "umd",
        umdNamedDefine: true
      },
      globalObject: 'typeof self !== "undefined" ? self : this'
    },
    externals: {
      react: {
        root: 'React',
        commonjs2: 'react',
        commonjs: 'react',
        amd: 'react'
      },
      'react-dom': {
        root: 'ReactDOM',
        commonjs2: 'react-dom',
        commonjs: 'react-dom',
        amd: 'react-dom'
      }
    }
  }
  

• 若必须直接将产物放入CRA的src目录测试，在构建产物index.js的第一行添加/* eslint-disable */注释，禁用该文件的ESLint检查即可。

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