私有NPM的React组件npm install报错，npm link正常，求原因排查

这种情况我之前也碰到过好几次，核心原因其实是本地npm link直接引用源码和**npm install安装打包后产物**的运行机制差异导致的。下面是几个最常见的排查方向：

1. 打包配置未正确输出组件导出 #

本地开发时，npm link会直接使用你的源码文件，而发布到私有仓库的是打包后的产物。如果打包工具（比如Rollup/Webpack）的配置有问题，就会导致产物里没有正确导出组件：

• 检查打包配置的output项，确保libraryTarget设置正确（React组件推荐umd或commonjs2）；
• 确认入口文件指向的是正确的组件导出文件；
• 可以直接去项目的node_modules/你的包名目录下，打开package.json的main字段指向的文件，看看是否有正确的export语句。

2. 导出与导入的方式不匹配 #

这是最容易踩坑的点：

• 如果你的组件是默认导出（export default MyComponent），但项目里用了命名导入（import { MyComponent } from '你的包名'），反之亦然；
• npm link时，本地的Babel或React的模块解析可能会“容错”这种不匹配，但打包后的产物严格遵循ES模块规范，就会直接返回undefined；
• 快速验证：检查组件源码的导出方式，再核对项目里的导入代码，确保两者完全一致。

3. package.json字段配置错误 #

私有包的package.json里的入口字段如果配置错误，项目就找不到正确的组件导出：

• 确认main（CommonJS入口）和module（ES模块入口）都指向正确的打包产物文件；
• 如果你的包包含副作用代码（比如全局样式），不要把sideEffects设为false，否则Tree Shaking可能会把组件误删，导致返回undefined。

4. 打包时未将React设为外部依赖 #

如果打包组件时把React也打包进去了，项目安装后会出现两个React实例，导致组件无法被正确识别：

• 检查打包配置，把react和react-dom设为外部依赖：
  • Rollup：在配置里添加external: ['react', 'react-dom']
  • Webpack：添加externals: { react: 'React', 'react-dom': 'ReactDOM' }
• 这样打包后的产物会使用项目本身的React实例，避免冲突。

5. 缓存或依赖残留问题 #

有时候npm缓存了旧版本的包，或者项目依赖有残留：

• 执行npm cache clean --force清除npm缓存，然后重新安装你的私有包；
• 也可以尝试删除项目的node_modules和package-lock.json（或yarn.lock），重新执行npm install。

内容的提问来源于stack exchange，提问作者Gilad Lev-Ari