Next.js项目中使用自定义React UI Kit Hooks报错求助

错误本质 #

这个报错的核心原因是自定义UI Kit打包时将React/ReactDOM一同打包进了产物，导致Next.js项目中同时存在两个独立的React实例，Hooks API无法关联到正确的React上下文，最终触发Cannot read properties of null错误。

分步解决方案 #

1. 配置Vite打包规则，排除React依赖 #

修改UI Kit项目中的vite.config.js，将React和ReactDOM标记为外部依赖，避免打包工具把它们打入最终产物：

// vite.config.js
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  build: {
    lib: {
      entry: 'src/index.js', // 替换为你的UI Kit入口文件路径
      name: 'MyCustomUIKit',
      fileName: (format) => `my-custom-ui-kit.${format}.js`
    },
    rollupOptions: {
      // 外部化React和ReactDOM，让宿主项目提供依赖
      external: ['react', 'react-dom'],
      output: {
        // 为UMD格式提供全局变量映射（可选）
        globals: {
          react: 'React',
          'react-dom': 'ReactDOM'
        }
      }
    }
  }
})

2. 声明Peer依赖，规范版本兼容 #

在UI Kit的package.json中添加peerDependencies，明确要求使用方提供兼容版本的React：

{
  "name": "my-custom-ui-kit",
  "version": "1.0.0",
  "peerDependencies": {
    "react": "^17.0.0 || ^18.0.0",
    "react-dom": "^17.0.0 || ^18.0.0"
  },
  "devDependencies": {
    "react": "^18.0.0",
    "react-dom": "^18.0.0"
  }
}

3. Next.js项目中正常使用UI Kit #

在Next.js项目安装UI Kit后，直接导入组件即可（Next.js会自动处理Peer依赖的版本匹配）：

// app/page.js (Next.js 13 App Router示例)
import { Card } from 'my-custom-ui-kit'

export default function Home() {
  return (
    <div className="p-8">
      <Card title="测试卡片">
        <p>自定义UI Kit组件已正常集成Hooks</p>
      </Card>
    </div>
  )
}

额外排查项 #

• 执行npm ls react检查Next.js项目中是否存在重复的React实例，确保只有顶层的一个React依赖
• 若UI Kit使用了其他第三方库（如styled-components），同样需要将其设为Peer依赖或外部化

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