我们经常发布文档更新,此页面的翻译可能仍在进行中。有关最新信息,请访问英文文档。如果此页面上的翻译有问题,请告诉我们

配置 npm 用于 GitHub 包

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

GitHub Packages is available with GitHub Free, GitHub Pro, GitHub Free for organizations, GitHub Team, GitHub Enterprise Cloud, GitHub Enterprise Server 2.22, and GitHub One.


GitHub Packages 不适用于使用旧版按仓库计划的帐户所拥有的私有仓库。 GitHub Packages 可用于 GitHub Free、GitHub Pro、组织的 GitHub Free、GitHub Team、GitHub Enterprise Cloud 和 GitHub One。 更多信息请参阅“GitHub 的产品”。

本文内容

Did this doc help you?

注:安装或发布 Docker 映像时,GitHub Packages 当前不支持外部图层,如 Windows 映像。

向 GitHub Packages 验证

您需要访问令牌才能发布、安装和删除 GitHub Packages 中的包。 您可以使用个人访问令牌直接向 GitHub Packages 或 GitHub API 验证您的用户名。 创建个人访问令牌时,可根据需要为令牌分配不同的作用域。

To authenticate using a GitHub Actions workflow:

  • For package registries (PACKAGE-REGISTRY.pkg.github.com/OWNER/REPOSITORY/IMAGE-NAME), you can use a GITHUB_TOKEN.
  • For the container registry (ghcr.io/OWNER/IMAGE-NAME), you must use a personal access token.

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

您必须使用具有适当范围的个人访问令牌才可在 GitHub Packages 中发布和安装。 更多信息请参阅“关于 GitHub Packages”。

通过编辑您的每用户 ~/.npmrc 文件以包含个人访问令牌,或者在命令行上使用用户名和个人访问令牌登录 npm,您可以使用 npm 向 GitHub Packages 验证。

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

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

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

"repository" : {
    "type" : "git",
    "url": "ssh://git@github.com/OWNER/REPOSITORY.git",
    "directory": "packages/name"
  },

使用 GITHUB_TOKEN 进行身份验证

如果您使用的是 GitHub Actions 工作流程,可以使用 GITHUB_TOKEN 发布和使用 GitHub Packages 中的软件包,而无需存储和管理个人访问令牌。 更多信息请参阅“使用 GITHUB_TOKEN 验证身份”。

发布包

默认情况下,GitHub Packages 将包发布到您在 package.json 文件的名称字段中指定的 GitHub 仓库。 例如,您要发布一个名为 @my-org/test 的包到 my-org/test GitHub 仓库。 通过在包目录中包含 README.md 文件,您可以添加包列表页面的摘要。 更多信息请参阅 npm 文档中的“使用 package.json”和“如何创建 Node.js 模块”。

通过在 package.json 文件中包含 URL 字段,您可以将多个包发布到同一个 GitHub 仓库。 更多信息请参阅“将多个包发布到同一个仓库”。

您可以使用项目中的本地 .npmrc 文件或使用 package.json 中的 publishConfig 选项来设置项目的作用域映射。 GitHub Packages 只支持作用域内的 npm 包。 作用域内的包具有名称格式 @owner/name。 作用域内的包总是以 @ 符号开头。 您可能需要更新 package.json 中的名称以使用作用域内的名称。 例如,"name": "@codertocat/hello-world-npm"

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

使用本地 .npmrc 文件发布包

您可以使用 .npmrc 文件来配置项目的作用域映射。 在 .npmrc 文件中,使用 GitHub Packages URL 和帐户所有者,使 account owner so GitHub Packages 知道将包请求路由到何处。 使用 .npmrc 文件防止其他开发者意外地将包发布到 npmjs.org 而不是 GitHub Packages。 由于不支持大写字母,因此,即使您的 GitHub 用户或组织名称中包含大写字母,也必须对仓库所有者使用小写字母。

  1. 向 GitHub Packages 验证。 更多信息请参阅“向 GitHub Packages 验证”。

  2. 在与 package.json 文件相同的目录中,创建或编辑 .npmrc 文件以包含指定 GitHub Packages URL 和帐户所有者的行。 将 OWNER 替换为拥有项目所在仓库的用户或组织帐户的名称。

    registry=https://npm.pkg.github.com/OWNER
  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,则仓库字段应为 git://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,则仓库字段应为 git://github.com/my-org/test.git

  3. 发布包:

    $ npm publish

将多个包发布到同一个仓库

要将多个包发布到同一个仓库,您可以在每个包的 package.json 文件的 repository 字段中包含 GitHub 仓库的 URL。

为确保仓库的 URL 正确,请将 REPOSITORY 替换为要发布的包所在仓库的名称,将 OWNER 替换为拥有该仓库的 GitHub 用户或组织帐户的名称。

GitHub Packages 将根据该 URL 匹配仓库,而不是根据包名称。 如果您在仓库根目录的外部存储 package.json 文件,您可以使用 directory 字段指定 GitHub Packages 可找到 package.json 文件的位置。

"repository" : {
    "type" : "git",
    "url": "ssh://git@github.com/OWNER/REPOSITORY.git",
    "directory": "packages/name"
  },

安装包

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

默认情况下,您可以从一个组织添加包。 更多信息请参阅从其他组织安装包

还需要将 .npmrc 文件添加到项目,使所有安装包的请求都会通过 GitHub Packages。 通过 GitHub Packages 路由所有包请求时,您可以使用 npmjs.com 作用域内和作用域外的包。 更多信息请参阅 npm 文档中的“npm 作用域”。

  1. 向 GitHub Packages 验证。 更多信息请参阅“向 GitHub Packages 验证”。

  2. 在与 package.json 文件相同的目录中,创建或编辑 .npmrc 文件以包含指定 GitHub Packages URL 和帐户所有者的行。 将 OWNER 替换为拥有项目所在仓库的用户或组织帐户的名称。

    registry=https://npm.pkg.github.com/OWNER
  3. .npmrc 文件添加到 GitHub Packages 可在其中找到您的项目的仓库。 更多信息请参阅“使用命令行添加文件到仓库”。

  4. 配置项目中的 package.json 使用要安装的包。 要将包依赖项添加到 GitHub Packages 的 package.json 文件,请指定完整的作用域内包名称,例如 @my-org/server。 对于来自 npmjs.com 的包,请指定全名,例如 @babel/core@lodash。 例如,以下 package.json@octo-org/octo-app 包用作依赖项。

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

    $ npm install

从其他组织安装包

默认情况下,您只能使用来自一个组织的 GitHub Packages 包。 默认情况下,您只能使用来自一个组织的 GitHub Packages 包。 由于不支持大写字母,因此,即使您的 GitHub 用户或组织名称中包含大写字母,也必须对仓库所有者使用小写字母。

registry=https://npm.pkg.github.comOWNER
@OWNER:registry=npm.pkg.github.com
@OWNER:registry=npm.pkg.github.com

延伸阅读

Did this doc help you?