React开发中forwardRef组件调用useState触发Invalid Hook Call错误求助

首先处理代码中已存在的明显异常 #

对照你贴的业务代码，先修这两个直接问题：

1. 调整useImperativeHandle的调用顺序，修正闭包问题
   原代码中先调用useImperativeHandle，后定义removeAnnotation函数，会导致暴露给父组件的方法拿不到正确的引用。调整为：

   // 先定义方法
   const removeAnnotation = useCallback((id: string) => {
     deleteAnnotation(id);
   }, [deleteAnnotation]);
   // 再调用Hooks暴露方法，补上依赖数组
   useImperativeHandle(ref, () => ({ removeAnnotation }), [removeAnnotation]);
   

2. 删掉多余的导入
   代码里的import { debug } from 'console';是Node.js环境的内置模块导入，浏览器端运行时会触发模块解析错误，直接删除这行即可。

对照三类常见根因逐一排查 #

1. React与ReactDOM版本不匹配 #

• 执行npm ls react react-dom查看本地安装的版本，确保两者的主版本、次版本号完全一致（例如同为18.2.0，不能出现React18和ReactDOM17的搭配）
• 如果版本不一致，统一安装相同版本即可：npm install react@指定版本 react-dom@同版本 --save

2. 违反Hooks使用规则 #

• 检查所有Hooks（包括你自定义的usePDF/useAnnotations/useTextMap）的调用位置，确保没有放在if判断、for循环、事件回调、普通工具函数等非组件顶层的位置
• 检查是否误把函数组件当普通函数直接调用（比如写Annotator()而非用JSX语法写<Annotator />渲染），这种情况也会触发Hooks执行上下文错误

3. 运行时存在多份React实例 #

这类问题在开发可复用组件（比如当前的PDF标注组件）时发生率极高：

• 执行npm ls react查看输出，如果看到react存在多个嵌套的版本路径，说明存在多实例
• 修复方式：
  • 业务项目开发场景：在打包配置（webpack/vite）中将react和react-dom标记为外部依赖，不把React代码打包进业务产物
  • 组件库开发场景：把react、react-dom配置为对等依赖（peerDependencies），不要把React作为生产依赖打进组件包

快速定位验证方法 #

在报错的useState代码行前加一行打印：

console.log('当前组件内的React引用:', React);

再在项目入口文件的最顶部加一行相同的打印，对比两次打印的React对象引用：如果引用地址不一致，就说明是多React实例的问题，按对应方案修复即可。

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