主项目引入本地React组件库组件运行报错如何排查解决

问题背景 #

使用React、TypeScript、Rollup与Styled Components搭建组件库，开发接近完成时遇到联调问题：组件库内完成ButtonBase按钮组件开发导出后，主项目通过本地路径安装组件库可正常导入组件，但运行时触发报错，报错截图如下：

测试时仅对React默认初始页面做了如下修改：

import "./App.css";

import { ButtonBase } from "aab-react-emerald";

function App() {
  return (
    <div className="App">
      <header className="App-header">
        <ButtonBase>Button</ButtonBase>
      </header>
    </div>
  );
}

export default App;

对比组件库与主项目的package.json配置未发现明显问题，以下为两个项目移除无关内容后的精简配置：

组件库 package.json 配置 #

{
  "devDependencies": {
    "@rollup/plugin-commonjs": "^22.0.1",
    "@rollup/plugin-node-resolve": "^13.3.0",
    "@rollup/plugin-typescript": "^8.3.3",
    "@storybook/addon-actions": "^6.5.9",
    "@storybook/addon-essentials": "^6.5.9",
    "@storybook/addon-interactions": "^6.5.9",
    "@storybook/addon-links": "^6.5.9",
    "@storybook/builder-webpack5": "^6.5.9",
    "@storybook/manager-webpack5": "^6.5.9",
    "@storybook/node-logger": "^6.5.9",
    "@storybook/preset-create-react-app": "^4.1.2",
    "@storybook/react": "^6.5.9",
    "@storybook/testing-library": "^0.0.13",
    "@testing-library/jest-dom": "^5.16.4",
    "@testing-library/react": "^13.3.0",
    "@testing-library/user-event": "^13.5.0",
    "@types/jest": "^28.1.4",
    "@types/node": "^18.0.3",
    "@types/react": "^18.0.15",
    "@types/react-dom": "^18.0.6",
    "@types/styled-components": "^5.1.25",
    "babel-plugin-named-exports-order": "^0.0.2",
    "prop-types": "^15.8.1",
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
    "react-scripts": "5.0.1",
    "rollup": "^2.76.0",
    "rollup-plugin-dts": "^4.2.2",
    "rollup-plugin-peer-deps-external": "^2.2.4",
    "styled-components": "^5.3.5",
    "tsconfig-paths-webpack-plugin": "^3.5.2",
    "tslib": "^2.4.0",
    "typescript": "^4.7.4",
    "webpack": "^5.73.0"
  },
  "peerDependencies": {
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
    "styled-components": "^5.3.5"
  }
}

主项目 package.json 配置 #

{
  "dependencies": {
    "@testing-library/jest-dom": "^5.16.4",
    "@testing-library/react": "^13.3.0",
    "@testing-library/user-event": "^13.5.0",
    "@types/jest": "^27.5.2",
    "@types/node": "^16.11.43",
    "@types/react": "^18.0.15",
    "@types/react-dom": "^18.0.6",
    "aab-react-emerald": "file:../../aab-react-emerald",
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
    "react-scripts": "5.0.1",
    "styled-components": "^5.3.5",
    "typescript": "^4.7.4",
    "web-vitals": "^2.1.4"
  }
}

排查方向（按优先级从高到低） #

• 重复依赖实例问题：这是file:协议本地安装组件库的最高发问题。本地软链安装时包管理器不会自动隔离peerDependencies，会直接将组件库devDependencies里的react、react-dom、styled-components带入主项目依赖树，导致运行时存在两份依赖副本，触发hooks调用异常、组件渲染报错。先检查主项目node_modules/aab-react-emerald目录下是否存在嵌套的react、styled-components依赖包，如果存在直接删除嵌套依赖目录，或在组件库根目录执行npm pack生成tgz压缩包后再在主项目安装，规避软链带来的依赖重复问题。
• Rollup打包配置校验：检查rollup配置是否正确将react、react-dom、styled-components标记为external，确认rollup-plugin-peer-deps-external放在plugins数组最前位置保证生效，避免把上述依赖打包进组件库产物引发重复实例。同时检查组件库package.json是否正确配置main、module、types字段，指向正确的打包产物路径，避免主项目加载到未编译的源码文件。
• Styled Components版本一致性校验：确认组件库和主项目安装的styled-components版本完全一致，本地联调时如果两个项目的styled-components存在小版本差异，会导致样式上下文不共享、组件渲染报错。可在主项目执行npm ls styled-components查看完整依赖树，确认不存在多版本实例。
• 导出逻辑校验：检查组件库入口文件是否正确导出ButtonBase，打开Rollup打包后的产物文件，搜索ButtonBase确认导出语句存在，避免导出undefined导致的渲染报错。
• TS配置兼容性校验：检查组件库tsconfig是否开启esModuleInterop，jsx配置是否匹配React18的react-jsx模式，避免编译后的jsx运行时调用逻辑和主项目不兼容。

内容的提问来源于stack exchange，提问作者Ricardo de Vries