跳至主要内容

使用 npm 注册表

您可以配置 npm 将软件包发布到 GitHub Packages,并在 npm 项目中使用存储在 GitHub Packages 上的软件包作为依赖项。

谁可以使用此功能?

GitHub Packages 可用于 GitHub 免费版、GitHub 专业版、GitHub 组织免费版、GitHub 团队版、GitHub Enterprise Cloud 和 GitHub Enterprise Server 3.0 或更高版本。


对于使用旧版每个存储库计划的帐户拥有的私有存储库,GitHub Packages 不可用。此外,使用旧版每个存储库计划的帐户无法访问支持细粒度权限的注册表,因为这些帐户按存储库计费。有关支持细粒度权限的注册表列表,请参阅“GitHub Packages 的权限”。有关更多信息,请参阅“GitHub 的计划”。

对 GitHub Packages 进行身份验证

GitHub Packages 仅支持使用个人访问令牌(经典)进行身份验证。有关更多信息,请参阅“管理您的个人访问令牌”。

您需要访问令牌才能发布、安装和删除私有、内部和公共软件包。

您可以使用个人访问令牌(经典)对 GitHub Packages 或 GitHub API 进行身份验证。创建个人访问令牌(经典)时,您可以根据需要为令牌分配不同的作用域。有关个人访问令牌(经典)与软件包相关的作用域的更多信息,请参阅“GitHub Packages 的权限”。

要在 GitHub Actions 工作流中对 GitHub Packages 注册表进行身份验证,您可以使用

  • GITHUB_TOKEN 发布与工作流存储库关联的软件包。
  • 至少具有 read:packages 作用域的个人访问令牌(经典)来安装与其他私有存储库关联的软件包(GITHUB_TOKEN 无法访问)。

在 GitHub Actions 工作流中进行身份验证

此注册表支持细粒度权限。对于支持细粒度权限的注册表,如果您的 GitHub Actions 工作流正在使用个人访问令牌对注册表进行身份验证,我们强烈建议您更新工作流以使用 GITHUB_TOKEN。有关更新使用个人访问令牌对注册表进行身份验证的工作流的指南,请参阅“使用 GitHub Actions 发布和安装软件包”。

注意

GitHub Actions 工作流使用 REST API 删除和恢复软件包的功能目前处于公开预览阶段,可能随时更改。

如果令牌对软件包具有 admin 权限,则可以在 GitHub Actions 工作流中使用 GITHUB_TOKEN 通过 REST API 删除或恢复软件包。使用工作流发布软件包的存储库以及您已明确连接到软件包的存储库会自动获得对存储库中软件包的 admin 权限。

有关 GITHUB_TOKEN 的更多信息,请参阅“自动令牌身份验证”。有关在 Actions 中使用注册表的最佳实践的更多信息,请参阅“GitHub Actions 的安全强化”。

您还可以选择独立为 GitHub Codespaces 和 GitHub Actions 提供软件包的访问权限。有关更多信息,请参阅“配置软件包的访问控制和可见性”和“配置软件包的访问控制和可见性”。

使用个人访问令牌进行身份验证

您必须使用具有适当作用域的个人访问令牌(经典)才能在 GitHub Packages 中发布和安装软件包。有关更多信息,请参阅“GitHub Packages 简介”。

您可以通过编辑您的每个用户~/.npmrc文件以包含您的个人访问令牌(经典),或通过使用您的用户名和个人访问令牌在命令行上登录 npm,来对 GitHub Packages 进行身份验证。

要通过将您的个人访问令牌(经典)添加到您的~/.npmrc文件中进行身份验证,请编辑项目的~/.npmrc文件以包含以下行,将 TOKEN 替换为您的个人访问令牌。如果不存在,请创建一个新的~/.npmrc文件。

//npm.pkg.github.com/:_authToken=TOKEN

要通过登录 npm 进行身份验证,请使用 npm login 命令,将 USERNAME 替换为您的 GitHub 用户名,TOKEN 替换为您的个人访问令牌(经典),并将 PUBLIC-EMAIL-ADDRESS 替换为您的电子邮件地址。

如果您使用的是 npm CLI 版本 9 或更高版本,并且正在使用命令行登录或注销私有注册表,则应使用 --auth-type=legacy 选项从提示中读取您的身份验证详细信息,而不是使用通过浏览器的默认登录流程。有关更多信息,请参阅 npm-login

如果 GitHub Packages 不是您使用 npm 的默认软件包注册表,并且您想使用 npm audit 命令,建议您在对 GitHub Packages 进行身份验证时,使用 --scope 标志以及托管软件包的命名空间(软件包的作用域范围的个人帐户或组织)。

$ npm login --scope=@NAMESPACE --auth-type=legacy --registry=https://npm.pkg.github.com

> Username: USERNAME
> Password: TOKEN

发布软件包

注意

  • 软件包名称和作用域只能使用小写字母。
  • npm 版本的 tarball 大小必须小于 256MB。

GitHub Packages 注册表将 npm 软件包存储在您的组织或个人帐户中,并允许您将软件包与存储库关联。您可以选择是否从存储库继承权限,或独立于存储库设置细粒度权限。

首次发布软件包时,默认可见性为私有。要更改可见性或设置访问权限,请参阅“配置软件包的访问控制和可见性”。有关将已发布的软件包与存储库链接的更多信息,请参阅“将存储库连接到软件包”。

在发布软件包后,您可以立即通过在 package.json 文件中包含 repository 字段来将软件包连接到存储库。您还可以使用此方法将多个软件包连接到同一存储库。有关更多信息,请参阅“将多个软件包发布到同一存储库”。

注意

如果您发布与存储库链接的软件包,则该软件包会自动继承链接存储库的访问权限,并且链接存储库中的 GitHub Actions 工作流会自动获得对该软件包的访问权限,除非您的组织已禁用访问权限的自动继承。有关更多信息,请参阅“配置软件包的访问控制和可见性”。

您可以使用项目中的本地.npmrc文件或package.json中的publishConfig选项来设置项目的范围映射。GitHub Packages 仅支持作用域 npm 包。作用域包的名称格式为@NAMESPACE/PACKAGE-NAME。作用域包始终以@符号开头。您可能需要更新package.json中的名称以使用作用域名称。例如,如果您是用户octocat并且您的包名为test,则您将分配作用域包名称如下:"name": "@octocat/test"

发布包后,您可以在 GitHub 上查看该包。有关更多信息,请参阅“查看包”。

使用本地.npmrc文件发布包

您可以使用.npmrc文件配置项目的范围映射。在.npmrc文件中,使用 GitHub Packages URL 和帐户所有者,以便 GitHub Packages 知道将包请求路由到哪里。使用.npmrc文件可以防止其他开发人员意外地将包发布到 npmjs.org 而不是 GitHub Packages。

  1. 认证到 GitHub Packages。有关更多信息,请参阅“认证到 GitHub Packages”。

  2. 在与您的package.json文件相同的目录中,创建或编辑一个.npmrc文件以包含一行,指定 GitHub Packages URL 和托管包的命名空间。将NAMESPACE替换为包将作用域到的用户或组织帐户的名称。

    @NAMESPACE:registry=https://npm.pkg.github.com
    
  3. .npmrc文件添加到 GitHub Packages 可以找到您的项目的存储库中。有关更多信息,请参阅“将文件添加到存储库”。

  4. 验证项目package.json中包的名称。name字段必须包含包的作用域和名称。例如,如果您的包名为“test”,并且您将其发布到“My-org”GitHub 组织,则package.json中的name字段应为@my-org/test

  5. 验证项目package.json中的repository字段。repository字段必须与您的 GitHub 存储库的 URL 匹配。例如,如果您的存储库 URL 为github.com/my-org/test,则存储库字段应为https://github.com/my-org/test.git

  6. 发布包

    npm publish
    

使用package.json文件中的publishConfig发布包

您可以使用package.json文件中的publishConfig元素来指定要发布包的注册表。有关更多信息,请参阅 npm 文档中的“publishConfig”。

  1. 编辑包的package.json文件并包含publishConfig条目。

    "publishConfig": {
      "registry": "https://npm.pkg.github.com"
    },
    
  2. 验证项目package.json中的repository字段。repository字段必须与您的 GitHub 存储库的 URL 匹配。例如,如果您的存储库 URL 为github.com/my-org/test,则存储库字段应为https://github.com/my-org/test.git

  3. 发布包

    npm publish
    

将多个包发布到同一存储库

要发布多个包并将其链接到同一存储库,您可以在每个包的package.json文件的repository字段中包含 GitHub 存储库的 URL。有关更多信息,请参阅 npm 文档中的“创建 package.json 文件”和“创建 Node.js 模块”。

要确保存储库的 URL 正确,请将REPOSITORY替换为包含要发布的包的存储库的名称,并将OWNER替换为拥有该存储库的 GitHub 上的个人帐户或组织的名称。

GitHub Packages 将根据 URL 匹配存储库。

"repository":"https://github.com/OWNER/REPOSITORY",

安装包

您可以通过将包作为依赖项添加到项目的package.json文件中来安装来自 GitHub Packages 的包。有关在项目中使用package.json的更多信息,请参阅 npm 文档中的“使用 package.json”。

默认情况下,您可以添加来自一个组织的包。有关更多信息,请参阅“安装来自其他组织的包”。

您还需要将.npmrc文件添加到您的项目中,以便所有安装包的请求都将通过 GitHub Packages 进行。当您通过 GitHub Packages 路由所有包请求时,您可以使用来自npmjs.org的作用域和非作用域包。有关更多信息,请参阅 npm 文档中的“npm-scope”。

  1. 认证到 GitHub Packages。有关更多信息,请参阅“认证到 GitHub Packages”。

  2. 在与您的package.json文件相同的目录中,创建或编辑一个.npmrc文件以包含一行,指定 GitHub Packages URL 和托管包的命名空间。将NAMESPACE替换为包将作用域到的用户或组织帐户的名称。

    @NAMESPACE:registry=https://npm.pkg.github.com
    
  3. .npmrc文件添加到 GitHub Packages 可以找到您的项目的存储库中。有关更多信息,请参阅“将文件添加到存储库”。

  4. 配置项目中的package.json以使用您要安装的包。要将您的包依赖项添加到 GitHub Packages 的package.json文件中,请指定完整的带作用域的包名称,例如@my-org/server。对于来自npmjs.com的包,请指定完整名称,例如@babel/corelodash。将ORGANIZATION_NAME/PACKAGE_NAME替换为您的包依赖项。

    {
      "name": "@my-org/server",
      "version": "1.0.0",
      "description": "Server app that uses the ORGANIZATION_NAME/PACKAGE_NAME package",
      "main": "index.js",
      "author": "",
      "license": "MIT",
      "dependencies": {
        "ORGANIZATION_NAME/PACKAGE_NAME": "1.0.0"
      }
    }
    
  5. 安装包。

    npm install
    

安装来自其他组织的包

默认情况下,您只能使用来自一个组织的 GitHub Packages 包。如果您想将包请求路由到多个组织和用户,则可以向.npmrc文件添加其他行,将NAMESPACE替换为包作用域到的个人帐户或组织的名称。

@NAMESPACE:registry=https://npm.pkg.github.com
@NAMESPACE:registry=https://npm.pkg.github.com