TypeScript React项目使用npm link关联私有NPM包报Module not found错误

1. npm link后包从package.json移除的问题 #

这是npm v5.x及以上版本的默认行为：执行npm link <包名>时，如果本地package.json已声明对应依赖，npm会自动替换为软链接，同时移除原有依赖的版本声明，属于正常设计逻辑。
如果需要保留package.json中的依赖声明，执行link命令时添加--save参数即可：

npm link @CompanyName/linked-module --save

2. 模块找不到的报错问题 #

2.1 优先校验包名一致性 #

你当前三个场景下的包名完全不匹配，是直接报错的核心原因：

• 运行时报错查找的包名为 @CompanyName/Company-package
• 主项目package.json声明的依赖名为 @CompanyName/NPM-LINKED-MODULE
• 私有NPM包自身package.json的name字段为 @CompanyName/linked-module
  必须保证三者完全一致：私有包name字段是什么值，主项目就声明对应值的依赖、link命令就写对应值、代码中import时也使用完全相同的名称。

2.2 确认私有包已完成构建 #

你的私有包配置的入口文件为dist/bundle.js，每次修改包代码后，都需要先执行私有包的构建命令（通常为npm run build）生成dist目录下的产物，否则会因为找不到入口文件报模块不存在错误。

2.3 适配react-scripts的软链接限制 #

你使用的是react-scripts 4.0.1版本，默认webpack配置禁用了软链接解析，这也是为什么Laravel项目可以正常使用、React项目报错的核心原因，可通过以下方案解决：
无需eject项目的方案：启动时添加NODE_PRESERVE_SYMLINKS=1环境变量，修改主项目package.json的scripts.start字段：

// macOS/Linux 环境
"start": "NODE_PRESERVE_SYMLINKS=1 react-scripts start"

如果是Windows环境，先安装cross-env：

npm install cross-env --save-dev

再修改start命令：

"start": "cross-env NODE_PRESERVE_SYMLINKS=1 react-scripts start"

2.4 兜底排查方案 #

如果上述操作后仍有问题，按以下步骤重置即可：

• 执行npm cache clean --force清除npm缓存
• 删除主项目的node_modules目录和package-lock.json文件
• 执行npm install重新安装依赖
• 重新执行npm link命令关联私有包

内容的提问来源于stack exchange，提问作者HP-Liam