webpack打包React组件适配浏览器与Node SSR的Hooks调用错误问题

错误根因 #

你遇到的问题本质是React多实例冲突，且UMD打包时的externals配置没有兼容多环境规则：

• 不配置externals时，webpack会把React全量打进产物，Node环境下引入组件时，本地node_modules还有一份独立的React，两份实例同时存在就会触发Hook调用校验失败
• 直接配置externals: {react: 'react'}时，打包后的产物在所有环境都会尝试从外部引入react依赖，浏览器环境没有对应的全局模块/依赖，自然运行失败

解决方案 #

调整webpack的externals配置，为不同模块化规范指定对应的依赖引入规则，修改后的配置如下：

externals: {
  react: {
    commonjs: 'react',
    commonjs2: 'react',
    amd: 'react',
    root: 'React'
  },
  'react-dom': {
    commonjs: 'react-dom',
    commonjs2: 'react-dom',
    amd: 'react-dom',
    root: 'ReactDOM'
  }
}

该配置的适配逻辑如下：

• Node/CommonJS环境下，自动从本地node_modules引入react、react-dom依赖，不会将这两个库打包进产物，避免出现多份React实例导致Hook报错
• 浏览器端通过script标签直接引入时，会从全局变量window.React、window.ReactDOM获取依赖，你只需要在引入组件产物前，先加载对应版本的React、ReactDOM资源，确保全局挂载了对应变量即可
• 浏览器端通过webpack、vite等构建工具引入组件包时，构建工具会自动从node_modules查找react、react-dom依赖，无需额外配置即可正常运行

如果你的场景需要支持浏览器端无需提前引入React、直接用script标签加载组件，可以再新增一份独立构建配置：不配置externals，输出文件名改为index.browser.js，同时在package.json中新增"browser": "./public/index.browser.js"，这样工具链会自动为浏览器环境选用内置了React的版本，Node环境还是沿用external后的轻量化版本。

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