含私有包与yarnrc.yml的GitHub Actions工作流触发Registry 403错误

问题背景 #

我在搭建GitHub Actions工作流时，需要用Yarn安装包含GitHub Packages私有包的依赖。本地开发环境的.yarnrc.yml配置如下：

nodeLinker: node-modules

yarnPath: .yarn/releases/yarn-3.6.4.cjs
npmScopes:
  ourCustomScope:
    npmRegistryServer: https://npm.pkg.github.com
    npmAuthToken: ${GITHUB_PACKAGES_TOKEN}

对应的工作流配置：

name: CI - Lint
on:
  push:
    branches:
      - main
      - dev
  pull_request:

concurrency:
  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
  cancel-in-progress: true

env:
  GITHUB_PACKAGES_TOKEN: ${{secrets.GITHUB_TOKEN}}
    
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Use Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20.x'
          cache: 'yarn'
          registry-url: https://npm.pkg.github.com
          scope: '@ourCustomScope'
      - name: Install dependencies
        run: yarn --immutable
        env:
          GITHUB_PACKAGES_TOKEN: ${{secrets.GITHUB_TOKEN}}
      - name: Lint & Format
        run: yarn lint

错误信息 #

工作流在「Install Dependencies」步骤失败，报错：

Run yarn --immutable
➤ YN0000: ┌ Resolution step
Resolution step
➤ YN0000: └ Completed in 0s 576ms
➤ YN0000: ┌ Fetch step
Fetch step
➤ YN0035: @ourCustomScope/our-package@npm:0.5.0::__archiveUrl=https%3A%2F%2Fnpm.pkg.github.com%2Fdownload%2F%40ourscope%2Four-package%2F0.5.0%2Fefc87a511fa65b9572efce9df2c50342b4864bbc: The remote server failed to provide the requested resource
➤ YN0035:   Response Code: 403 (Forbidden)
➤ YN0035:   Request Method: GET
➤ YN0035:   Request URL: https://npm.pkg.github.com/download/@ourScope/our-package/0.5.0/efc87a511fa65b9572efce9df2c50342b4864bbc
➤ YN0000: └ Completed in 2m 29s
➤ YN0000: Failed with errors in 2m 30s
Error: Process completed with exit code 1.

原因分析 #

1. 默认GITHUB_TOKEN权限不足 #

GitHub Actions提供的默认GITHUB_TOKEN仅拥有当前仓库的权限，无法访问其他私有仓库中的GitHub Packages。如果你的私有包托管在另一个仓库，这个token会因权限不够返回403。

2. Scope名称不匹配 #

从报错URL可以看到，请求的包是@ourScope/our-package，但你.yarnrc.yml中配置的npmScopes是ourCustomScope，两者名称（甚至大小写）不一致，导致Yarn没有使用你配置的私有仓库地址和token，而是走了默认逻辑，最终触发权限错误。

3. 配置冲突 #

setup-node步骤中设置了registry-url和scope，这会和本地.yarnrc.yml的配置产生冲突。Yarn 3在解析配置时可能优先级混乱，导致token没有正确传递到私有仓库请求中。

修复方案 #

方案一：修正Scope名称匹配 #

确保.yarnrc.yml中的scope名称和私有包的scope完全一致（注意GitHub Packages的scope大小写敏感）：

nodeLinker: node-modules

yarnPath: .yarn/releases/yarn-3.6.4.cjs
npmScopes:
  ourScope: # 和包的scope保持一致
    npmRegistryServer: https://npm.pkg.github.com
    npmAuthToken: ${GITHUB_PACKAGES_TOKEN}

方案二：使用PAT替代默认GITHUB_TOKEN #

1. 创建一个Personal Access Token (PAT)，勾选read:packages权限；如果私有包在其他仓库，还要确保PAT拥有该仓库的访问权限。
2. 在当前仓库的「Settings → Secrets and variables → Actions」中添加这个PAT，命名为GH_PAT。
3. 修改工作流中的环境变量，替换为这个PAT：

# ... 其他配置不变
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Use Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20.x'
          cache: 'yarn'
      - name: Install dependencies
        run: yarn --immutable
        env:
          GITHUB_PACKAGES_TOKEN: ${{ secrets.GH_PAT }} # 替换为你的PAT
      - name: Lint & Format
        run: yarn lint

方案三：移除冲突的setup-node配置 #

删除setup-node中的registry-url和scope参数，让Yarn完全使用本地.yarnrc.yml的配置，避免双重配置冲突：

- name: Use Node.js
  uses: actions/setup-node@v4
  with:
    node-version: '20.x'
    cache: 'yarn'

内容的提问来源于stack exchange，提问作者Phil Lucks