使用 npm 注册表

向 GitHub Packages 验证

Note

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 发布和安装包”。

Note

GitHub Actions 工作流使用 REST API 删除和还原包的功能目前为公共预览版，可能随时更改。

如果令牌具有对包的 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

发布包

Note

包名称和作用域只能使用小写字母。

npm 版本的 tarball 必须小于 256MB。

GitHub Packages 注册表会将 npm 包存储在组织或个人帐户中，并允许将包与存储库关联。可以选择是从存储库继承权限，还是独立于存储库设置精细权限。

首次发布包时，默认可见性是私有的。要更改可见性或设置访问权限，请参阅“配置包的访问控制和可见性”。有关将已发布的包与仓库链接的详细信息，请参阅将仓库连接到包。

一旦包发布，即可通过在 package.json 文件中包含 repository 字段来将包连接到存储库。还可以使用此方法将多个包连接至同一个存储库。有关详细信息，请参阅将多个包发布到同一仓库。

Note

如果发布链接到存储库的包，该包会自动继承链接存储库的访问权限，链接存储库中的 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。

向 GitHub Packages 验证。有关详细信息，请参阅“向 GitHub Packages 进行身份验证”。
在与 package.json 文件相同的目录中，创建或编辑 .npmrc 文件以包含指定 GitHub Packages URL 和托管包的命名空间的行。将 NAMESPACE 替换为作为包限定范围的用户或组织帐户的名称。
```
@NAMESPACE:registry=https://npm.pkg.github.com
```
将 .npmrc 文件添加到 GitHub Packages 可在其中找到项目的存储库。有关详细信息，请参阅“添加文件到仓库”。
验证项目的 package.json 中包的名称。 name 字段必须包含包的作用域和名称。例如，如果包名为“test”，并且要将其发布到“My-org”GitHub 组织，则 package.json 中的 name 字段应为 @my-org/test。
验证项目 package.json 中的 repository 字段。 repository 字段必须与 GitHub 存储库的 URL 匹配。例如，如果存储库 URL 是 github.com/my-org/test，则存储库字段应为 https://github.com/my-org/test.git。
发布包：
```
npm publish
```

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

可以使用 package.json 文件中的 publishConfig 元素来指定要发布包的注册表。有关详细信息，请参阅 npm 文档中的 publishConfig。

编辑包的 package.json 文件并包含一个 publishConfig 条目。
```
"publishConfig": {
  "registry": "https://npm.pkg.github.com"
},
```
验证项目 package.json 中的 repository 字段。 repository 字段必须与 GitHub 存储库的 URL 匹配。例如，如果存储库 URL 是 github.com/my-org/test，则存储库字段应为 https://github.com/my-org/test.git。
发布包：
```
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。

向 GitHub Packages 验证。有关详细信息，请参阅“向 GitHub Packages 进行身份验证”。
在与 package.json 文件相同的目录中，创建或编辑 .npmrc 文件以包含指定 GitHub Packages URL 和托管包的命名空间的行。将 NAMESPACE 替换为作为包限定范围的用户或组织帐户的名称。
```
@NAMESPACE:registry=https://npm.pkg.github.com
```
将 .npmrc 文件添加到 GitHub Packages 可在其中找到项目的存储库。有关详细信息，请参阅“添加文件到仓库”。
在项目中配置 package.json 以使用要安装的包。若要将包依赖项添加到 GitHub Packages 的 package.json 文件，请指定完整的作用域内包名称，例如 @my-org/server。对于来自 npmjs.com 的包，请指定全名，例如 @babel/core 或 lodash。将 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"
  }
}
```
安装此包。
```
npm install
```

从其他组织安装包

默认情况下，您只能使用来自一个组织的 GitHub Packages 包。如果想将包请求路由到多个组织和用户，可以在 .npmrc __ 文件中添加额外的行，将 NAMESPACE 替换为包范围所属的用户或组织帐户的名称。

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

谁可以使用此功能？

本文内容

向 GitHub Packages 验证

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

使用 personal access token

发布包

使用本地 .npmrc 文件发布包

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

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

安装包

从其他组织安装包