Skip to main content

使用 npm 注册表

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

GitHub Packages 适用于 GitHub Free、GitHub Pro、面向组织的 GitHub Free、GitHub Team、GitHub Enterprise Cloud、GitHub Enterprise Server 3.0 或更高版本以及 GitHub AE。
GitHub Packages 不适用于使用旧版按仓库计划的帐户所拥有的私有仓库。 此外,使用旧版按存储库计划的帐户无法访问支持精细权限的注册表,因为这些帐户按存储库计费。 有关支持精细权限的注册表的列表,请参阅“关于 GitHub Packages 的权限”。 有关详细信息,请参阅“GitHub 的计划”。

向 GitHub Packages 验证

GitHub Packages 仅支持使用 personal access token (classic) 进行身份验证。 有关详细信息,请参阅“管理个人访问令牌”。

需要访问令牌才能发布、安装和删除专用、内部和公共包。

可使用 personal access token (classic) 向 GitHub Packages 或 GitHub API 进行身份验证。 创建 personal access token (classic) 时,可根据需要为令牌分配不同的作用域。 有关 personal access token (classic) 的包相关范围的详细信息,请参阅“关于 GitHub Packages 的权限”。

要在 GitHub Actions 工作流程内向 GitHub Packages 注册表验证,您可以使用:

  • GITHUB_TOKEN 发布与工作流存储库相关联的包。
  • 范围至少为 read:packages 的 personal access token (classic),用于安装与其他专用存储库(GITHUB_TOKEN 无法访问)关联的包。

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

此注册表支持精细权限。 对于支持精细权限的注册表,如果 GitHub Actions 工作流使用 personal access token 向注册表进行身份验证,则强烈建议更新工作流以使用 GITHUB_TOKEN。 有关如何更新通过 personal access token 向注册表进行身份验证的工作流的指南,请参阅“使用 GitHub Actions 发布和安装包”。

注意:GitHub Actions 工作流使用 REST API 删除和还原包的功能目前提供公共 beta 版本,可能会发生更改。

如果令牌具有对包的 admin 权限,你可以在 GitHub Actions 工作流中使用 GITHUB_TOKEN,通过 REST API 来删除或还原包。 使用工作流发布包的存储库,以及已经显式连接到包的存储库,会自动获得对存储库中包的 admin 权限。

有关 GITHUB_TOKEN 的详细信息,请参阅“自动令牌身份验证”。 有关在操作中使用注册表时的最佳做法的详细信息,请参阅“GitHub Actions 的安全强化”。

还可以选择为 GitHub Codespaces 和 GitHub Actions 单独授予对包的访问权限。 有关详细信息,请参阅“配置包的访问控制和可见性”和“配置包的访问控制和可见性”。

使用 personal access token

进行身份验证

必须使用具有适当范围的 personal access token (classic) 才可在 GitHub Packages 中发布和安装包。 有关详细信息,请参阅“GitHub Packages 简介”。

通过编辑你的每用户 ~/.npmrc 文件以包含 personal access token (classic),或者在命令行上使用用户名和 personal access token 登录 npm,你可以使用 npm 对 GitHub Packages 进行身份验证。

若要通过将 personal access token (classic) 添加到 ~/.npmrc 文件来进行身份验证,请编辑项目的 ~/.npmrc 文件以包含以下行,将 TOKEN 替换为你的 personal access token 。 创建一个新的 ~/.npmrc 文件(如果不存在)。

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

若要通过登录到 npm 进行身份验证,请使用 npm login 命令,将 USERNAME 替换为你的 GitHub 用户名,将 TOKEN 替换为你的 personal access token (classic),并将 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"
    },
    
    1. 验证项目 package.json 中的 repository 字段。 repository 字段必须与 GitHub 存储库的 URL 匹配。 例如,如果存储库 URL 是 github.com/my-org/test,则存储库字段应为 https://github.com/my-org/test.git
  2. 发布包:

    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 作用域”。

  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