GitHub Actions拉取GitHub私有npm包遇401未授权错误求助

问题背景 #

为Node项目通过GitHub Actions拉取my-org组织下的私有npm包，编写了生成.npmrc文件的Action代码：

> ${{ inputs.npmrc_path }}
echo "@my-org:registry=https://npm.pkg.github.com/" >> ${{ inputs.npmrc_path }}
if [ ! -z "${{ inputs.github_token }}" ]; then
    echo "//npm.pkg.github.com/:_authToken=${{ inputs.github_token }}" >> ${{ inputs.npmrc_path }}
    echo "@my-org:always-auth=true" >> ${{ inputs.npmrc_path }}
fi
echo "registry=https://registry.npmjs.org" >> ${{ inputs.npmrc_path }}
if [ ! -z "${{ inputs.nexus_url }}" ]; then
    auth=$(echo -n '${{ inputs.nexus_user }}:${{ inputs.nexus_password }}' | base64)
    echo "${{ inputs.nexus_url }}:_auth=$auth" >> ${{ inputs.npmrc_path }}
    echo "always-auth=true" >> ${{ inputs.npmrc_path }}
fi

调用Action时已传入全权限GitHub Token，自身拥有目标包管理员权限，调用仓库也已获得包访问权限，但执行时触发401错误：

npm error code E401
npm error 401 Unauthorized - GET https://npm.pkg.github.com/@my-org%2fpackage - authentication token not provided
npm error A complete log of this run can be found in: /home/runner/.npm/_logs/...log

项目package.json依赖配置：

"dependencies": {
    ...
    "@my-org/package": "0.0.6"
  },
  "devDependencies": {
    ...
  },
  "engines": {
    "node": "6.17.0"
  }
}

本地环境可正常下载该包，需排查问题原因。

排查与解决方法 #

1. Node版本兼容性缺陷 #

项目指定的Node 6.17.0配套的npm版本过低，对.npmrc中作用域与认证的关联解析存在问题，无法正确将@my-org作用域的请求与GitHub Packages的token绑定，导致请求时未携带认证信息。

解决：升级Node版本至8.x及以上（推荐LTS版本），在GitHub Actions中通过actions/setup-node指定：

- name: Setup Node.js
  uses: actions/setup-node@v4
  with:
    node-version: '16.x'
    cache: 'npm'

2. .npmrc配置顺序与全局覆盖问题 #

当前代码中，全局registry配置在作用域配置之后虽不影响优先级，但旧版npm可能出现解析异常；同时Nexus配置中的全局always-auth=true会覆盖@my-org的作用域认证配置，导致认证逻辑混乱。

修正后的生成代码：

# 清空目标文件，避免旧配置干扰
> ${{ inputs.npmrc_path }}
# 配置私有包作用域及认证
echo "@my-org:registry=https://npm.pkg.github.com/" >> ${{ inputs.npmrc_path }}
if [ ! -z "${{ inputs.github_token }}" ]; then
    echo "//npm.pkg.github.com/:_authToken=${{ inputs.github_token }}" >> ${{ inputs.npmrc_path }}
    echo "@my-org:always-auth=true" >> ${{ inputs.npmrc_path }}
fi
# 配置全局公共registry
echo "registry=https://registry.npmjs.org" >> ${{ inputs.npmrc_path }}
# Nexus配置单独处理，避免全局覆盖
if [ ! -z "${{ inputs.nexus_url }}" ]; then
    auth=$(echo -n "${{ inputs.nexus_user }}:${{ inputs.nexus_password }}" | base64)
    echo "${{ inputs.nexus_url }}:_auth=$auth" >> ${{ inputs.npmrc_path }}
    # 仅给Nexus域名添加always-auth，而非全局
    echo "${{ inputs.nexus_url }}:always-auth=true" >> ${{ inputs.npmrc_path }}
fi

3. GitHub Token权限验证 #

确认传入的GitHub Token具备read:packages权限，即使是全权限Token，也要确保组织层面未限制该Token的包访问权限，可在Token设置中明确勾选read:packages。

4. 缓存干扰清理 #

GitHub Actions的npm缓存可能保留旧的.npmrc或认证信息，导致新配置未生效。安装依赖前执行清理：

- name: Clean npm cache
  run: npm cache clean --force

内容的提问来源于stack exchange，提问作者Isabel Roman