引入GitHub私有NPM依赖报模块找不到错误如何解决

问题复现场景 #

已完成操作：

• 私有React组件包已成功发布到对应GitHub仓库的GitHub Packages
• 消费端使用GitHub Packages页面提供的安装命令执行安装，命令行提示依赖添加成功
• 消费端项目package.json同级目录下已创建.npmrc配置文件，初始配置如下：

//npm.pkg.github.com/:_authToken=<拥有读权限的个人认证Token>
registry=https://npm.pkg.github.com/<对应仓库名>

• 在App.js中按包名导入组件：

import { HelloWorld } from '<package.json中声明的完整包名>';

触发报错：

Module not found: Error: Can't resolve '@my_github/private-repo' in <本地项目路径>
排查1小时以上未定位到配置或操作遗漏，不确定故障来自React组件导出配置还是引入方式错误。

根因排查与修复 #

按优先级从高到低逐一排查：

1. 修正.npmrc配置错误（最高发问题）
   初始配置有两个核心错误：
   • GitHub Packages的registry路径不需要拼接具体仓库名，仅需写到域名层级即可
   • 不要全局替换npm registry为GitHub Packages源，否则所有公共npm包都会去GitHub拉取，必然出错，需要针对包的scope单独指定源
     正确配置示例（包名为@my_github/private-repo时）：

   @my_github:registry=https://npm.pkg.github.com
   //npm.pkg.github.com/:_authToken=<你的拥有read:packages权限的认证Token>
   always-auth=true
   

   改完配置后删除项目下的node_modules文件夹和package-lock.json文件，重新执行npm install再尝试导入。
2. 校验已安装包的文件完整性
   打开消费端项目node_modules目录下对应的私有包文件夹，逐一核对：
   • 包根目录package.json的name字段必须和导入时写的包名完全一致，大小写、scope前缀、包名不能有任何偏差
   • 检查package.json中main/module/exports字段指向的构建产物路径是否真实存在。90%以上的发布后找不到模块问题，都是因为package.json里没配置files字段，执行npm publish时没有把构建好的dist组件产物目录上传到GitHub Packages，导致包内只有package.json和说明文档，没有实际可执行的组件代码。如果是这个问题，需要在发布端的package.json里添加"files": ["dist"]（对应你的实际构建产物目录），重新发布版本后再在消费端安装新版本。
   • 核对组件导出方式：如果组件源码是export default HelloWorld的默认导出，导入时不能加大括号，要写import HelloWorld from '@my_github/private-repo'；只有源码用export { HelloWorld }做命名导出时，才需要加大括号导入。
3. 校验安装包的正确性
   如果源配置错误，npm可能拉取到本地缓存的同名空包、或者公共源上的同名占位包，可以直接查看node_modules下对应包的文件内容，确认是自己发布的组件版本，如果内容不对，执行npm cache clean --force清缓存后重新安装。
4. 权限校验
   确认使用的认证Token权限正确：经典Token需要勾选read:packages权限，细粒度Token需要授予对应仓库的包读取权限，且Token未过期。

内容的提问来源于stack exchange，提问作者J.R.