React组件库报错：Cannot read properties of null (reading 'useState')求助

核心原因 #

当组件库与业务项目中存在两个独立的React实例时，React Hook系统会因无法找到统一的上下文环境抛出错误——Hook依赖单一的React运行时实例，多实例会导致上下文丢失，触发Cannot read properties of null这类异常。

具体修复步骤 #

1. 调整组件库的package.json依赖配置 #

将React和ReactDOM从dependencies移至peerDependencies，同时添加peerDependenciesMeta明确依赖要求：

{
  "name": "your-component-library",
  "version": "1.0.0",
  "peerDependencies": {
    "react": "^17.0.0 || ^18.0.0",
    "react-dom": "^17.0.0 || ^18.0.0"
  },
  "peerDependenciesMeta": {
    "react": {
      "optional": false
    },
    "react-dom": {
      "optional": false
    }
  },
  "devDependencies": {
    "react": "^18.2.0",
    "react-dom": "^18.2.0"
    // 保留babel、rollup等其他开发依赖
  }
}

• peerDependencies：声明组件库依赖宿主项目提供的React版本，避免重复安装。
• devDependencies：仅在组件库开发、构建阶段使用React，打包时不会将React打入产物。

2. 配置打包工具排除React #

使用Rollup或Webpack打包组件库时，需将React和ReactDOM标记为外部依赖，避免打包进组件库产物：

• Rollup示例（rollup.config.js）：

export default {
  // 其他配置
  external: ['react', 'react-dom'],
  output: {
    // 其他配置
    globals: {
      react: 'React',
      'react-dom': 'ReactDOM'
    }
  }
}

• Webpack示例（webpack.config.js）：

module.exports = {
  // 其他配置
  externals: {
    react: 'React',
    'react-dom': 'ReactDOM'
  }
}

配置后，组件库会直接引用宿主项目的React实例，而非自带副本。

3. 清理依赖并重新安装 #

• 在组件库根目录执行：

rm -rf node_modules package-lock.json # yarn项目替换为yarn.lock
npm install # yarn项目替换为yarn install

• 业务项目根目录执行相同操作，确保依赖环境干净。

4. 强制统一React版本（若存在多版本残留） #

在业务项目的package.json中添加版本强制配置，确保所有子依赖使用同一版本React：

// npm项目
"overrides": {
  "react": "^18.2.0",
  "react-dom": "^18.2.0"
}

// yarn项目
"resolutions": {
  "react": "^18.2.0",
  "react-dom": "^18.2.0"
}

添加后重新安装依赖即可生效。

额外验证 #

检查组件代码中的React导入，确保是标准导入而非本地副本：

import React, { useState } from 'react';

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