使用npm link本地测试React组件库时出现useContext读取null错误

问题根源 #

本地使用npm link时，组件库和测试项目会各自加载独立的React实例，而useContext依赖同一个React上下文环境，跨实例调用就会出现Cannot read properties of null (reading 'useContext')错误。发布后正常是因为npm会自动处理peerDependencies，让组件库复用宿主项目的React实例。

解决方案 #

1. 正确配置组件库的peerDependencies

修改组件库的package.json，将react和react-dom从dependencies移到peerDependencies，同时保留在devDependencies供开发使用：

{
  "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"
    // 其他开发依赖
  }
}

这样组件库不会把React打包进产物，而是依赖宿主项目提供的React实例。

2. 让测试项目共享组件库的React实例

• 先在组件库项目执行npm link，把组件库注册到全局
• 进入测试项目，执行以下命令（替换为你的组件库实际路径）：

  # 让测试项目使用组件库的React实例，避免多实例冲突
  npm link ../path-to-your-library/node_modules/react
  # 再链接组件库
  npm link @efishery/onefish-antd
  

3. 用yalc替代npm link（更稳定的本地测试方案）

如果npm link的符号链接问题频繁出现，推荐用yalc模拟真实npm安装：

• 全局安装yalc：

  npm install -g yalc
  

• 在组件库项目执行：

  yalc publish
  

• 在测试项目添加组件库：

  yalc add @efishery/onefish-antd
  

• 组件库代码修改后，执行yalc push，测试项目会自动同步更新，完全避免多实例问题。

4. 检查打包工具的externals配置

如果用Rollup或Webpack打包组件库，确保将React和ReactDOM设为外部依赖，不打包进产物：

• Rollup示例：

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

• Webpack示例：

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

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