如何用tsc打包UMD格式React组件库并处理react/react-dom依赖问题

问题根因 #

你遇到的报错是两个原因共同导致的：

1. React 官方 UMD 包在浏览器全局挂载的变量名为首字母大写的 React、ReactDOM，而纯 tsc 打包生成的 UMD 文件，默认会直接用依赖的模块名（全小写的 react、react-dom）去全局作用域查找对应变量，自然匹配不到。
2. tsc 本身没有你猜测的 --addDeps 这类参数，无法单独通过 tsc 配置完成 UMD 模式下的外部依赖全局名映射。

你之前配置的 webpack externals 是你自己的业务项目引入 react-spinners 时的配置，和打包 react-spinners 这个库本身无关，不会解决当前问题。

解决方案 #

方案1：临时兼容（不修改打包逻辑） #

如果不想调整现有构建流程，可以在引入 react、react-dom 的 script 标签之后加一行全局变量映射，就能直接用现有打包好的 UMD 文件：

<script src="https://unpkg.com/react@17.0.2/umd/react.production.min.js"></script>
<script src="https://unpkg.com/react-dom@17.0.2/umd/react-dom.production.min.js"></script>
<script>
  // 映射为tsc生成的UMD需要的全小写变量名
  window.react = window.React;
  window['react-dom'] = window.ReactDOM;
</script>
<script src="https://unpkg.com/react-spinners@0.12.0-alpha.1/umd/index.js"></script>

方案2：调整构建流程（推荐） #

tsc 本身不适合单独用来打包带 peer 依赖的 UMD 类库，搭配 Rollup 可以很方便实现你要的效果，步骤如下：

1. 安装构建依赖：

npm install rollup @rollup/plugin-typescript @rollup/plugin-node-resolve @rollup/plugin-commonjs rollup-plugin-peer-deps-external -D

2. 新建 rollup.config.umd.js 配置文件：

import typescript from '@rollup/plugin-typescript';
import resolve from '@rollup/plugin-node-resolve';
import commonjs from '@rollup/plugin-commonjs';
import peerDepsExternal from 'rollup-plugin-peer-deps-external';

export default {
  input: 'src/index.tsx', // 替换为你实际的库入口路径
  output: {
    file: 'umd/index.js',
    format: 'umd',
    name: 'ReactSpinners', // 库暴露到全局的变量名，可自定义
    globals: {
      'react': 'React',
      'react-dom': 'ReactDOM'
    }
  },
  plugins: [
    peerDepsExternal(), // 自动将peerDependencies标记为外部依赖，不会打包进产物
    resolve(),
    commonjs(),
    typescript({ tsconfig: 'tsconfig.umd.json' })
  ]
};

3. 修改 package.json 里的构建命令：

"build:umd": "rollup --config rollup.config.umd.js"

调整后打包出的 UMD 文件会自动识别全局的 React、ReactDOM 变量，不需要额外做全局映射，直接按你之前的顺序引入即可正常使用。

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