Skip to main content

使用 npm 注册表

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

注意:这种包类型可能不适用于你的实例,因为站点管理员可以启用或禁用每种支持的包类型。 有关详细信息,请参阅“为企业配置包支持”。

已发布 npm 版本的限制

如果您发布超过 1,000npm 软件包版本到 GitHub Packages,在使用过程中可能会出现性能问题和超时。

将来,为了提高服务的性能,您将无法在 GitHub 上发布超过 1,000 个版本的包。 在达到此限制之前发布的任何版本仍将是可读的。

如果达到此限制,请考虑删除包版本或联系支持人员寻求帮助。 实施此限制后,我们的文档将就此限制进行更新。 有关详细信息,请参阅“删除和还原包”或“联系支持人员”。

向 GitHub Packages 验证

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

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

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

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

使用 personal access token 进行身份验证

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

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

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

如果实例启用了子域隔离:

//npm.HOSTNAME//:_authToken=TOKEN

如果实例禁用了子域隔离:

//HOSTNAME/_registry/npm/:_authToken=TOKEN

若要通过登录到 npm 进行身份验证,请使用 npm login 命令,将 USERNAME 替换为你的 GitHub 用户名,将 TOKEN 替换为你的 personal access token,并将 PUBLIC-EMAIL-ADDRESS 替换为你的电子邮件地址 。

如果 GitHub Packages 不是使用 npm 的默认包注册表,并且你要使用 npm audit 命令,我们建议你在对 GitHub Packages 进行身份验证时,将 --scope 标志与包的所有者一起使用。

如果实例启用了子域隔离:

$ npm login --scope=@OWNER --registry=https://npm.HOSTNAME/

> Username: USERNAME
> Password: TOKEN
> Email: PUBLIC-EMAIL-ADDRESS

如果实例禁用了子域隔离:

$ npm login --scope=@OWNER --registry=https://HOSTNAME/_registry/npm/
> Username: USERNAME
> Password: TOKEN
> Email: PUBLIC-EMAIL-ADDRESS

发布包

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

默认情况下,GitHub Packages 将包发布到你在 package.json 文件的名称字段中指定的 GitHub 存储库。 例如,你要将一个名为 @my-org/test 的包发布到 my-org/test GitHub 存储库。 如果运行 npm v8.5.3 或更高版本,则可以通过在包目录中包含 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 和帐户所有者,以便 GitHub Packages 知道将包请求路由到何处。 使用 .npmrc 文件防止其他开发人员意外地将包发布到 npmjs.org 而不是 GitHub Packages。

  1. 向 GitHub Packages 验证。 有关详细信息,请参阅“向 GitHub Packages 进行身份验证”。 2. 在与 package.json 文件相同的目录中,创建或编辑 .npmrc 文件以包含指定 GitHub Packages URL 和帐户所有者的行。 将 OWNER 替换为拥有项目所在存储库的用户或组织帐户的名称。

    如果启用了子域隔离:

    @OWNER:registry=https://npm.HOSTNAME

    如果禁用了子域隔离:

    @OWNER:registry=https://HOSTNAME/_registry/npm
  2. 将 .npmrc 文件添加到 GitHub Packages 可在其中找到项目的存储库。 有关详细信息,请参阅“将文件添加到存储库”。

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

  4. 验证项目 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”。

  1. 编辑包的 package.json 文件并包含一个 publishConfig 条目。 如果实例启用了子域隔离:

    "publishConfig": {
      "registry": "https://npm.HOSTNAME/"
    },

    如果实例禁用了子域隔离:

    "publishConfig": {
       "registry": "https://HOSTNAME/_registry/npm/"
     },
    1. 验证项目 package.json 中的 repository 字段。 repository 字段必须与 GitHub 存储库的 URL 匹配。 例如,如果存储库 URL 是 github.com/my-org/test,则存储库字段应为 https://github.com/my-org/test.git。 1. 发布包:
    $ npm publish

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

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

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

GitHub Packages 将根据该 URL 匹配仓库,而不是根据包名称。

"repository":"https://HOSTNAME/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 和帐户所有者的行。 将 OWNER 替换为拥有项目所在存储库的用户或组织帐户的名称。

    如果启用了子域隔离:

    @OWNER:registry=https://npm.HOSTNAME

    如果禁用了子域隔离:

    @OWNER:registry=https://HOSTNAME/_registry/npm
  2. 将 .npmrc 文件添加到 GitHub Packages 可在其中找到项目的存储库。 有关详细信息,请参阅“将文件添加到存储库”。

  3. 在项目中配置 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"
      }
    }
    
  4. 安装此包。

    $ npm install

从其他组织安装包

默认情况下,您只能使用来自一个组织的 GitHub Packages 包。 如果想将包请求路由到多个组织和用户,可以在 .npmrc 文件中添加额外的行,将 HOSTNAME 替换为 your GitHub Enterprise Server instance 的主机名,并将 OWNER 替换为拥有项目所在存储库的用户或组织帐户的名称 。

如果实例启用了子域隔离:

@OWNER:registry=https://npm.HOSTNAME
@OWNER:registry=https://npm.HOSTNAME

如果实例禁用了子域隔离:

@OWNER:registry=https://HOSTNAME/_registry/npm
@OWNER:registry=https://HOSTNAME/_registry/npm

使用官方 NPM 注册表

GitHub Packages 允许访问 registry.npmjs.com 上的官方 NPM 注册表,前提是你的 GitHub Enterprise Server 管理员已启用此功能。 有关详细信息,请参阅连接到官方 NPM 注册表