向 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 文件的名称字段中指定的 GitHub 存储库。 例如,你要将一个名为 @my-org/test
的包发布到 my-org/test
GitHub 存储库。 如果运行 npm v8.5.3 或更高版本,则可以通过在包目录中包含 README.md 文件,为包列表页面添加一个摘要。 有关详细信息,请参阅 npm 文档中的“使用 package.json”和“如何创建 Node.js 模块”。
注意: 如果发布链接到存储库的包,该包会自动继承链接存储库的访问权限,链接存储库中的 GitHub Actions 工作流会自动获得对包的访问权限,除非你的组织已禁用访问权限的自动继承。 有关详细信息,请参阅“配置包的访问控制和可见性”。
通过在 package.json 文件中包含 URL
字段,可以将多个包发布到同一个 GitHub 存储库。 有关详细信息,请参阅“将多个包发布到同一存储库”。
可以使用项目中的本地 .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 进行身份验证”。 2. 在与
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
。 1. 发布包:$ 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
。 1. 发布包:
$ npm publish
- 验证项目 package.json 中的
将多个包发布到同一个仓库
若要将多个包发布和链接到同一存储库,可以在每个包的 package.json 文件的 repository
字段中包含 GitHub 存储库的 URL。
为确保仓库的 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 作用域”。
-
向 GitHub Packages 验证。 有关详细信息,请参阅“向 GitHub Packages 进行身份验证”。 2. 在与
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