GitHub Actions拉取私有npm包遇ERR_PNPM_FETCH_401未授权错误

问题背景 #

在monorepo架构下，使用GitHub Actions通过pnpm拉取GitHub Packages中的私有npm包时，触发ERR_PNPM_FETCH_401未授权错误，即使已按文档配置认证仍无法解决。

错误信息 #

ERR_PNPM_FETCH_401  GET https://npm.pkg.github.com/download/@francislagares/jobber-shared/1.0.5/17a9104c0c7f6c748907155929f68e617e94a62e: Unauthorized - 401
An authorization header was used: ***
These authorization settings were found:
//npm.pkg.github.com/:_authToken=NPM_[hidden]

当前配置 #

GitHub工作流文件 #

name: Tests

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest

    strategy:
      matrix:
        node-version: [22.x]

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup pnpm
        uses: pnpm/action-setup@v4
        with:
          run_install: false

      - name: Get pnpm store directory
        shell: bash
        run: |
          echo "STORE_PATH=$(pnpm store path | tr -d '\n')" >> $GITHUB_ENV

      - name: Use Node.js ${{ matrix.node-version }}
        uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
          registry-url: 'https://npm.pkg.github.com'
          scope: '@francislagares'

      - name: Setup pnpm cache
        uses: actions/cache@v3
        with:
          path: ${{ env.STORE_PATH }}
          key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
          restore-keys: |
            ${{ runner.os }}-pnpm-store-

      - name: Install Dependencies
        run: pnpm install
        env:
          NPM_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      - name: Generate Prisma ORM schema to the database
        run: pnpm prisma migrate deploy

      - name: Run Tests
        run: pnpm test:ci

.npmrc文件 #

@francislagares:registry=https://npm.pkg.github.com/francislagares
//npm.pkg.github.com/:_authToken=NPM_TOKEN

已尝试步骤 #

• 仓库设置中添加了拥有全部权限的GITHUB_TOKEN密钥
• 配置了.npmrc文件用于GitHub Packages认证
• 多次调整配置，错误仍存在

解决方案与排查思路 #

1. 修正.npmrc的环境变量引用方式 #

pnpm不会自动识别裸写的NPM_TOKEN，需要用${NPM_TOKEN}语法让环境变量生效。修改后的.npmrc：

@francislagares:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${NPM_TOKEN}

注意：registry地址无需追加用户名，https://npm.pkg.github.com即可正确匹配@francislagares scope。

2. 替换默认GITHUB_TOKEN为Personal Access Token (PAT) #

默认GITHUB_TOKEN仅对当前仓库有读写权限，若私有包存储在其他GitHub仓库，需要创建具备read:packages权限的PAT：

• 前往GitHub个人设置 → Developer settings → Personal access tokens → Tokens (classic)
• 生成新token，勾选read:packages权限
• 将该token存入仓库Secrets（命名为PACKAGE_READ_TOKEN）
• 调整工作流中的install步骤：

  - name: Install Dependencies
    run: pnpm install
    env:
      NPM_TOKEN: ${{ secrets.PACKAGE_READ_TOKEN }}
  

3. 避免Node.js配置与.npmrc冲突 #

actions/setup-node中设置的registry-url和scope会自动生成临时.npmrc，可能与本地.npmrc冲突。建议移除setup-node中的相关配置，完全依赖本地.npmrc：

- name: Use Node.js ${{ matrix.node-version }}
  uses: actions/setup-node@v4
  with:
    node-version: ${{ matrix.node-version }}

4. 调试认证信息是否生效 #

在install步骤前添加调试命令，确认环境变量和.npmrc配置：

- name: Debug auth config
  run: |
    echo "NPM_TOKEN exists: ${{ env.NPM_TOKEN != '' }}"
    cat .npmrc

（注意：不要直接打印$NPM_TOKEN值，避免泄露敏感信息）

5. 确认私有包的访问权限 #

前往GitHub Packages页面，检查@francislagares/jobber-shared包的权限设置：

• 确认PAT对应的用户或团队被添加为包的协作者
• 确认包的可见性设置为“私有”且授权用户可访问

6. 清理pnpm缓存 #

缓存的旧认证信息可能导致问题，在install前清理缓存：

- name: Clean pnpm cache
  run: pnpm store prune

内容的提问来源于stack exchange，提问作者Francis Lagares