使用Rollup构建的React NPM本地链接库引入依赖后无法渲染

核心原因：React多实例冲突 #

当你的Rollup配置把React、styled-components这类依赖打包进库文件，而测试用的CRA项目本身也安装了这些依赖时，会出现两个独立的React实例。React Hooks要求必须在同一个React实例下调用，否则会静默失效（无报错但不执行），这就是组件不渲染的根本原因。

具体修复步骤 #

1. 配置Rollup external外部化peer依赖 #

修改rollup.config.js，将React、react-dom、styled-components设为外部依赖，不让Rollup打包进最终产物：

import peerDepsExternal from 'rollup-plugin-peer-deps-external';
// 导入其他所需插件（如@rollup/plugin-babel、@rollup/plugin-node-resolve等）

export default {
  input: 'src/index.js', // 你的库入口文件路径
  output: [
    {
      file: 'dist/index.js',
      format: 'esm', // 推荐ES模块格式，兼容CRA的树摇优化
      sourcemap: true,
    },
  ],
  plugins: [
    peerDepsExternal(), // 自动识别package.json中的peerDependencies并设为external
    // 配置其他插件（babel转换、模块解析等）
  ],
  // 若不使用peerDepsExternal插件，可手动指定外部依赖
  // external: ['react', 'react-dom', 'styled-components'],
};

2. 完善package.json的依赖声明 #

在库项目的package.json中添加peer依赖，明确告知宿主项目需提供这些依赖：

{
  "peerDependencies": {
    "react": "^17.0.0 || ^18.0.0",
    "react-dom": "^17.0.0 || ^18.0.0",
    "styled-components": "^5.0.0 || ^6.0.0"
  },
  "devDependencies": {
    "react": "^18.0.0",
    "react-dom": "^18.0.0",
    "styled-components": "^6.0.0"
  }
}

• peerDependencies：告知用户安装你的库时，项目必须已存在对应版本的依赖
• devDependencies：仅用于库的开发阶段，不会被打包或强制用户安装

3. 重新打包并更新本地Link #

• 执行Rollup重新打包：rollup -c
• 若已存在旧Link，先在测试项目中解除：npm unlink your-library-name
• 重新建立Link：在库项目根目录执行npm link，再到CRA测试项目执行npm link your-library-name

4. 验证组件导出正确性 #

确保库入口文件正确导出组件：

// src/index.js
export { default as MyComponent } from './MyComponent';

检查dist/index.js中的导出逻辑是否与预期一致，避免导出错误导致组件无法正常导入。

额外排查点 #

• 打开浏览器DevTools的Console面板：可能存在隐藏的警告（如React Hook调用异常）
• 确认Rollup的Babel配置：是否正确使用@babel/preset-react处理React语法，保证Hook代码被正确转译

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