Yarn安装私有Node模块突发401未授权错误排查求助

问题背景 #

用Yarn 1.22.22管理GitHub私有Node模块依赖时，本地和App Center突然都无法完成安装，初始报错为401 Unauthorized，删除yarn.lock后报错变为unauthenticated: User cannot be authenticated with the token provided。已尝试重建~/.npmrc、执行yarn cache clean、删除锁文件等常规方案但无效，不过GitHub环境中（预构建脚本添加了yarn cache clean）可正常运行，重新生成仓库令牌也未解决问题。本地依赖版本：Yarn 1.22.22、npm 10.7.0、Node.js v20.15.1。

解决方案 #

1. 检查GitHub令牌的权限与范围 #

• 确保你的GitHub个人访问令牌（PAT）勾选了read:packages权限——若需要向私有仓库发包，还需额外勾选write:packages；同时确认该令牌对应的账号确实拥有目标私有模块的访问权限，比如是仓库成员或有权限的团队成员。
• 避免使用仓库级令牌，改用账号级PAT，仓库令牌权限范围有限，跨场景易失效。

2. 排查Yarn与npm的配置冲突 #

Yarn 1.x会读取npm的配置，但高版本npm（如10.x）的配置格式或优先级可能与Yarn 1.x不兼容：

• 直接通过Yarn命令配置私有源授权，不要仅依赖~/.npmrc：

  yarn config set npmAuthToken "你的GitHub PAT"
  yarn config set registry "https://registry.yarnpkg.com"
  yarn config set @<你的组织名>:registry "https://npm.pkg.github.com"
  

• 检查~/.yarnrc是否存在冲突配置，比如重复的源或令牌设置，删除冗余项后保存。

3. 彻底清理缓存与残留配置 #

常规缓存清理可能不彻底，执行以下操作：

• 直接删除Yarn的全局缓存目录（默认路径：~/.cache/yarn），而非仅执行yarn cache clean：

  rm -rf ~/.cache/yarn
  

• 检查项目根目录的.npmrc或.yarnrc文件，确保里面的令牌配置与全局配置一致，避免局部配置覆盖全局授权信息。

4. 适配App Center的环境变量配置 #

App Center环境中，全局配置文件可能未被正确加载，需通过环境变量传递授权信息：

• 在App Center的构建配置中添加环境变量：
  • NPM_AUTH_TOKEN: 你的GitHub PAT
  • YARN_NPM_AUTH_TOKEN: 你的GitHub PAT（Yarn 1.x会读取这个变量）
• 在App Center的预构建脚本中添加配置命令，确保构建时正确关联私有源：

  yarn config set @<你的组织名>:registry https://npm.pkg.github.com
  yarn config set npmAuthToken $YARN_NPM_AUTH_TOKEN
  

5. 检查Yarn版本与Node.js的兼容性 #

Yarn 1.22.22发布于2023年，与Node.js v20.x可能存在兼容性问题：

• 尝试将Node.js降级到v18.x LTS版本（Yarn 1.x对v18.x的兼容性更稳定），再重新执行依赖安装。
• 若不想降级Node.js，可尝试升级Yarn到1.x的最新稳定版，修复已知的授权相关Bug。

6. 确认私有模块的源路径正确性 #

确保package.json中私有模块的包名前缀与配置的私有源匹配：

• 比如私有模块为@my-org/my-package，则必须配置@my-org:registry=https://npm.pkg.github.com，不能遗漏组织名前缀。
• 若恢复了yarn.lock，检查其中私有模块的源地址是否为https://npm.pkg.github.com，而非其他镜像或错误地址。

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