无法使用GITHUB_TOKEN或PAT在私有GitHub注册表发布作用域NPM包

场景说明 #

在个人私有GitHub仓库中，尝试发布带作用域的包到npm.pkg.github.com，未创建组织，仅通过该私有仓库管理单体包。

错误1：使用secrets.GITHUB_TOKEN时的403错误 #

执行actions/setup-node@v3配合默认GITHUB_TOKEN后出现如下错误：

npm ERR! code E403
npm ERR! 403 403 Forbidden - PUT https://npm.pkg.github.com/@myscope%2fmypackage - Permission permission_denied: The requested installation does not exist.
npm ERR! 403 In most cases, you or one of your dependencies are requesting
npm ERR! 403 a package version that is forbidden by your security policy, or
npm ERR! 403 on a server you do not have access to.

原因 #

• 默认GITHUB_TOKEN权限不足：默认的GITHUB_TOKEN没有packages: write权限，无法创建或发布GitHub Packages包。
• 作用域与用户名不匹配：个人账号的GitHub Packages要求包的作用域必须和你的GitHub用户名完全一致，若使用自定义的@myscope而非你的用户名，系统会找不到对应的个人账号“安装项”，触发“installation does not exist”错误。

错误2：使用PAT时的403错误 #

使用个人访问令牌（PAT）后出现如下错误：

npm ERR! code E403
npm ERR! 403 403 Forbidden - PUT https://npm.pkg.github.com/@myscope%2fmypackage - Permission permission_denied: create_package
npm ERR! 403 In most cases, you or one of your dependencies are requesting
npm ERR! 403 a package version that is forbidden by your security policy, or
npm ERR! 403 on a server you do not have access to.

原因 #

• PAT权限缺失：生成PAT时未勾选write:packages权限，没有创建包的权限。
• 作用域不合法：同样存在包作用域与GitHub用户名不匹配的问题，个人账号无法使用自定义作用域，必须以自己的用户名作为包的作用域。

解决办法 #

• 修正包的作用域：确保package.json中的name字段格式为@你的GitHub用户名/包名，例如你的GitHub用户名是alice，则包名必须为@alice/mypackage。
• 配置GITHUB_TOKEN权限（推荐）：在GitHub Actions工作流中明确赋予packages: write权限，示例片段：

jobs:
  publish:
    runs-on: ubuntu-latest
    permissions:
      packages: write
      contents: read
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v3
        with:
          node-version: 20
          registry-url: 'https://npm.pkg.github.com'
          scope: '@你的GitHub用户名'
      - run: npm install
      - run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

• 正确配置PAT：
  • 生成PAT时，勾选write:packages、read:packages和repo权限（因仓库为私有）。
  • 将PAT添加到仓库的Secrets中（命名如GH_PACKAGES_TOKEN），在工作流中替换NODE_AUTH_TOKEN为该Secrets。
• 检查仓库Packages设置：确认仓库的Settings > Packages > GitHub Packages中没有限制个人包的发布权限。

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