NextJS 13/14本地组件库报错：Cannot read properties of null (reading 'useState')

核心原因分析 #

这个错误本质是React Hooks在非React组件上下文或React实例重复加载的环境中调用导致的。Next.js 13+的App Router模式下默认所有组件都是服务端组件，而本地组件库的组件若依赖客户端Hooks（如useState、useEffect），需满足三个关键条件：组件正确标记为客户端组件、项目与组件库共用同一React实例、组件库打包配置适配Next.js模块规范。

分步解决方案 #

1. 确保组件库组件正确标记"use client" #

即便你已尝试添加该指令，需注意：

• 必须放在组件文件最顶部，甚至早于所有import语句
• 所有嵌套的、依赖Hooks的子组件也需添加该指令
  示例组件库代码：

"use client"; // 必须是文件第一行代码
import React, { useState } from 'react';

export const CounterButton = () => {
  const [count, setCount] = useState(0);
  return <button onClick={() => setCount(count + 1)}>点击次数: {count}</button>;
};

2. 避免React重复加载（关键修复） #

本地组件库通过npm link/yarn link链接时，极易出现项目与组件库各自加载独立React实例的情况，导致Hooks调用失败。解决方法：

• 在组件库的package.json中，将React和ReactDOM标记为peerDependencies，而非dependencies或devDependencies：

  {
    "peerDependencies": {
      "react": "^18.0.0",
      "react-dom": "^18.0.0"
    }
  }
  

• 回到Next.js项目根目录，强制安装依赖以复用同一React实例：

  # npm用户
  npm install --force
  # yarn用户
  yarn install --force
  

• 若使用pnpm，需在项目.npmrc中添加：

  shamefully-hoist=true
  

3. 检查组件库打包配置 #

若组件库用Rollup、Vite等工具打包，需确保输出兼容Next.js的模块格式：

• 输出ES模块（ESModule），避免CommonJS格式导致的加载异常
• 配置external选项排除React和ReactDOM，让宿主项目提供这些依赖
  示例Rollup配置片段：

export default {
  external: ['react', 'react-dom'],
  output: {
    format: 'esm',
    dir: 'dist',
    preserveModules: true,
  },
};

4. 验证Next.js项目的tsconfig.json配置 #

确保项目tsconfig.json的compilerOptions使用Next.js 13+推荐的模块解析规则：

{
  "compilerOptions": {
    "moduleResolution": "bundler",
    "target": "ESNext",
    "module": "ESNext"
  }
}

5. 清理缓存并重新构建 #

• 清理Next.js本地缓存：

  rm -rf .next
  

• 清理组件库构建产物并重新打包：

  cd 你的组件库目录
  rm -rf dist
  npm run build
  

• 重启Next.js开发服务器：

  npm run dev
  

验证流程 #

1. 先确认组件库的纯辅助函数可正常调用（你已验证通过）
2. 测试单个仅依赖useState的简单组件
3. 逐步引入复杂组件，排查是否存在未标记"use client"的子组件

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