包注册表中的 npm 包

Node Package Manager (npm) 是 JavaScript 和 Node.js 的默认包管理器。开发者使用 npm 来共享和重用代码、管理依赖项，并简化项目工作流程。在 GitLab 中，npm 包在软件开发生命周期中扮演着至关重要的角色。

有关 npm 包管理器客户端使用的特定 API 端点的文档，请参阅 npm API 文档。

了解如何构建 npm 或 yarn 包。

观看 视频演示，了解如何将 npm 包发布到 GitLab 包注册表。

向包注册表进行身份验证

要发布或从私有项目或私有组安装包，您必须向包注册表进行身份验证。 如果项目或组是公开的，则无需进行身份验证。 如果项目是内部的，您必须是 GitLab 实例的注册用户。 匿名用户无法从内部项目拉取包。

要进行身份验证，您可以使用以下任一方式：

• 具有 api 范围的 个人访问令牌、组访问令牌 或 项目访问令牌
• 具有 read_package_registry、write_package_registry 或两者范围的 部署令牌
• 如果要通过 CI/CD 管道发布包，可以使用 CI/CD 作业令牌

如果您的组织使用双因素身份验证 (2FA)，您必须使用具有 api 范围的个人访问令牌。 有关更多信息，请参阅 令牌指南。

请勿使用此处未记录的身份验证方法。未记录的身份验证方法将来可能会被移除。

使用 .npmrc 文件

在与您的 package.json 相同的目录中创建或编辑 .npmrc 文件。在 .npmrc 文件中包含以下行：

  //<domain_name>/api/v4/projects/<project_id>/packages/npm/:_authToken="${NPM_TOKEN}"

例如：

//<domain_name>/api/v4/packages/npm/:_authToken="${NPM_TOKEN}"

//<domain_name>/api/v4/groups/<group_id>/-/packages/npm/:_authToken="${NPM_TOKEN}"

//<domain_name>/api/v4/projects/<project_id>/packages/npm/:_authToken="${NPM_TOKEN}"

使用 npm config set

执行以下操作：

npm config set -- //<domain_name>/:_authToken=<token>

根据您的 npm 版本，您可能需要对 URL 进行更改：

• 在 npm 版本 7 或更早版本中，使用端点的完整 URL。
• 在版本 8 及更高版本中，对于 _authToken 参数，您可以 使用 URI 片段代替完整 URL。组特定端点 不受支持。

例如：

npm config set -- //<domain_name>/api/v4/packages/npm/:_authToken=<token>

npm config set -- //<domain_name>/api/v4/groups/<group_id>/-/packages/npm/:_authToken=<token>

npm config set -- //<domain_name>/api/v4/projects/<project_id>/packages/npm/:_authToken=<token>

设置注册表 URL

要从 GitLab 包注册表发布或安装包，您需要配置 npm 以使用正确的注册表 URL。配置方法和 URL 结构取决于您是发布还是安装包。

在配置注册表 URL 之前，了解不同配置方法的范围很重要：

• .npmrc 文件：配置仅限于包含该文件的文件夹。
• npm config set 命令：这会修改全局 npm 配置，并影响您系统上运行的所有 npm 命令。
• package.json 中的 publishConfig：此配置特定于包，仅适用于发布该包时。

发布包时

发布包时，使用项目端点：

https://gitlab.example.com/api/v4/projects/<project_id>/packages/npm/

将 gitlab.example.com 替换为您的 GitLab 实例的域名，将 <project_id> 替换为您的项目 ID。 要配置此 URL，使用以下方法之一：

@scope:registry=https://gitlab.example.com/api/v4/projects/<project_id>/packages/npm/
//gitlab.example.com/api/v4/projects/<project_id>/packages/npm/:_authToken="${NPM_TOKEN}"

npm config set @scope:registry=https://gitlab.example.com/api/v4/projects/<project_id>/packages/npm/

{
  "publishConfig": {
    "@scope:registry": "https://gitlab.example.com/api/v4/projects/<project_id>/packages/npm/"
  }
}

将 @scope 替换为您的包的范围。

安装包时

安装包时，您可以使用项目、组或实例端点。相应的 URL 结构会有所不同。 要配置这些 URL，使用以下方法之一：

将 gitlab.example.com、<project_id>、<group_id> 和 @scope 替换为您的 GitLab 实例和包的适当值。

配置注册表 URL 后，您就可以向包注册表进行身份验证。

发布到 GitLab 包注册表

要将 npm 包发布到 GitLab 包注册表，您必须已进行 身份验证。

命名约定

根据包的安装方式，您可能需要遵循命名约定。

您可以使用三种 API 端点之一来安装包：

• 实例：当您在不同的 GitLab 组或自己的命名空间中有许多 npm 包时使用。
• 组：当您在同一组或子组下的不同项目中有许多 npm 包时使用。
• 项目：当您只有少数 npm 包且它们不在同一个 GitLab 组中使用时使用。

如果您计划从 项目 或 组 安装包，则无需遵循命名约定。

如果您计划从 实例 安装包，则必须使用 范围 来命名您的包。作用域包以 @ 开头，格式为 @owner/package-name。您可以在 .npmrc 文件中为您的包设置范围，并使用 package.json 中的 publishConfig 选项。

• 用于 @scope 的值是托管包的项目的根，而不是包源代码本身的项目的根。范围应为小写。
• 包名称可以是您想要的任何名称。

确保您的 package.json 文件中的包名称符合此约定：

"name": "@my-org/package-name"

使用命令行发布包

在 配置身份验证 后，使用以下命令发布 NPM 包：

npm publish

如果您使用 .npmrc 文件进行身份验证，请设置预期的环境变量：

NPM_TOKEN=<token> npm publish

如果上传的包有多个 package.json 文件，则只使用找到的第一个文件，其他文件将被忽略。

使用 CI/CD 管道发布包

通过 CI/CD 管道发布时，您可以使用 预定义变量 ${CI_PROJECT_ID} 和 ${CI_JOB_TOKEN} 来对项目包注册表进行身份验证。您可以使用这些变量在 CI/CD 作业执行期间创建用于身份验证的 .npmrc 文件。

在包含您的 package.json 的 GitLab 项目中，编辑或创建 .gitlab-ci.yml 文件。例如：

default:
  image: node:latest

stages:
  - deploy

publish-npm:
  stage: deploy
  script:
    - echo "@scope:registry=https://${CI_SERVER_HOST}/api/v4/projects/${CI_PROJECT_ID}/packages/npm/" > .npmrc
    - echo "//${CI_SERVER_HOST}/api/v4/projects/${CI_PROJECT_ID}/packages/npm/:_authToken=${CI_JOB_TOKEN}" >> .npmrc
    - npm publish

将 @scope 替换为正在发布的包的 范围。

当您的管道中的 publish-npm 作业运行时，您的包将被发布到包注册表。

安装包

如果多个包具有相同的名称和版本，安装包时将获取最新发布的包。

您可以从 GitLab 项目、组或实例安装包：

• 实例：当您在不同的 GitLab 组或自己的命名空间中有许多 npm 包时使用。
• 组：当您在同一 GitLab 组下的不同项目中有许多 npm 包时使用。
• 项目：当您只有少数 npm 包且它们不在同一个 GitLab 组中使用时使用。

从实例安装

先决条件：

• 包已根据作用域 命名约定 发布。

1. 向包注册表进行身份验证。

2. 设置注册表：

   npm config set @scope:registry https://<domain_name>.com/api/v4/packages/npm/

   • 将 @scope 替换为您正在从中安装项目的 顶级组。
   • 将 <domain_name> 替换为您的域名，例如 gitlab.com。

3. 安装包：

   npm install @scope/my-package

从组安装

1. 向包注册表进行身份验证。

2. 设置注册表：

   npm config set @scope:registry=https://<domain_name>/api/v4/groups/<group_id>/-/packages/npm/

   • 将 @scope 替换为您正在从中安装组的 顶级组。
   • 将 <domain_name> 替换为您的域名，例如 gitlab.com。
   • 将 <group_id> 替换为您的组 ID，在组主页上找到。

3. 安装包：

   npm install @scope/my-package

从项目安装

1. 向包注册表进行身份验证。

2. 设置注册表：

   npm config set @scope:registry=https://<domain_name>/api/v4/projects/<project_id>/packages/npm/

   • 将 @scope 替换为您正在从中安装项目的 顶级组。
   • 将 <domain_name> 替换为您的域名，例如 gitlab.com。
   • 将 <project_id> 替换为您的项目 ID，在 项目概述页面 上找到。

3. 安装包：

   npm install @scope/my-package

在 CI/CD 管道中安装包

在 CI/CD 管道中安装包时，您可以使用 预定义变量 ${CI_PROJECT_ID} 和 ${CI_JOB_TOKEN} 来对项目包注册表进行身份验证。您可以使用这些变量在 CI/CD 作业执行期间创建用于身份验证的 .npmrc 文件。

在包含您的 package.json 的 GitLab 项目中，编辑或创建 .gitlab-ci.yml 文件。例如：

default:
  image: node:latest

stages:
  - deploy

publish-npm:
  stage: deploy
  script:
    - echo "@scope:registry=https://${CI_SERVER_HOST}/api/v4/projects/${CI_PROJECT_ID}/packages/npm/" > .npmrc
    - echo "//${CI_SERVER_HOST}/api/v4/projects/${CI_PROJECT_ID}/packages/npm/:_authToken=${CI_JOB_TOKEN}" >> .npmrc
    - npm install @scope/my-package

将 @scope 替换为正在安装的包的 范围，以及包名称。

前面的示例使用项目级端点。要使用组级或实例级端点，请按照 从组安装 或 从实例安装 中的描述配置注册表和身份验证令牌 URL。

包转发到 npmjs.com

当在包注册表中找不到 npm 包时，GitLab 会响应 HTTP 重定向，以便请求客户端可以将请求重新发送到 npmjs.com。

管理员可以在 持续集成设置 中禁用此行为。

组所有者可以在组 包和注册表 设置中禁用此行为。

改进在 epic 3608 中跟踪。

弃用包

您可以弃用包，以便在获取包时显示弃用警告。

先决条件：

• 您拥有删除包所需的 权限。
• 您已 向包注册表进行身份验证。

从命令行运行：

npm deprecate @scope/package "弃用消息"

CLI 也接受 @scope/package 的版本范围。例如：

npm deprecate @scope/package "所有包版本已弃用"
npm deprecate @scope/[email protected] "仅版本 1.0.1 已弃用"
npm deprecate @scope/package@"< 1.0.5" "所有小于 1.0.5 的包版本已弃用"

当包被弃用时，其状态将更新为 deprecated。

移除弃用警告

要移除包的弃用警告，为消息指定 ""（空字符串）。例如：

npm deprecate @scope/package ""

当包的弃用警告被移除时，其状态将更新为 default。

有用的提示

从其他组织安装 npm 包

您可以将包请求路由到 GitLab 外的组织和用户。

为此，向您的 .npmrc 文件添加行。将 @my-other-org 替换为拥有您项目存储库的命名空间或组，并使用您的组织 URL。名称区分大小写，必须与您的组或命名空间的名称完全匹配。

@scope:registry=https://my_domain_name.com/api/v4/packages/npm/
@my-other-org:registry=https://my_domain_name.example.com/api/v4/packages/npm/

npm 元数据

GitLab 包注册表向 npm 客户端公开以下属性。 这些类似于 简化的元数据格式：

• name
• versions
  • name
  • version
  • deprecated
  • dependencies
  • devDependencies
  • bundleDependencies
  • peerDependencies
  • bin
  • directories
  • dist
  • engines
  • _hasShrinkwrap
  • hasInstallScript: 如果此版本有安装脚本，则为 true。

添加 npm 分发标签

您可以为新发布的包添加 分发标签。 标签是可选的，并且一次只能分配给一个包。

当您发布不带标签的包时，默认会添加 latest 标签。 当您安装包而不指定标签或版本时，将使用 latest 标签。

支持的 dist-tag 命令示例：

npm publish @scope/package --tag               # 使用新标签发布包
npm dist-tag add @scope/package@version my-tag # 为现有包添加标签
npm dist-tag ls @scope/package                 # 列出包下的所有标签
npm dist-tag rm @scope/package@version my-tag  # 从包中删除标签
npm install @scope/package@my-tag              # 安装特定标签

从 CI/CD

您可以使用 CI_JOB_TOKEN 或 部署令牌 在 GitLab CI/CD 作业中运行 npm dist-tag 命令。

先决条件：

• 您拥有 npm 版本 6.9.1 或更高版本。在早期版本中，由于 npm 6.9.0 中的错误，删除分发标签会失败。

例如：

npm-deploy-job:
  script:
    - echo "//${CI_SERVER_HOST}/api/v4/projects/${CI_PROJECT_ID}/packages/npm/:_authToken=${CI_JOB_TOKEN}">.npmrc
    - npm dist-tag add @scope/package@version my-tag

审计 npm 包

GitLab 支持 npm audit 命令，允许您检查包的已知漏洞。

使用 npm audit

先决条件：

• 向包注册表配置身份验证。
• 设置注册表 URL。

要运行安全审计，您可以运行以下命令：

npm audit --registry=https://gitlab.example.com/api/v4/packages/npm/

或者，如果您已经设置了注册表配置：

npm audit

npm audit 命令检查您的依赖项是否存在已知漏洞，并提供报告。

npm audit 工作流程

当您针对 GitLab 包注册表运行 npm audit 时，会出现以下两种情况之一：

1. 如果启用了包转发（默认），GitLab 会将审计请求转发到 npmjs.com 以获取公共和私有包的漏洞信息。
2. 如果禁用了包转发，GitLab 将返回空结果集。GitLab 不会独立扫描包的漏洞。

要了解有关包转发设置的更多信息，请参阅 包转发到 npmjs.com。

重要安全注意事项

如果您未将 GitLab 指定为您的包注册表（无论是使用 --registry 标志还是将其设置为 .npmrc 文件中的默认注册表），审计请求将转到公共 npm 注册表。

在这种情况下，请求正文包含您项目中所有包的信息，包括您的私有 GitLab 包。

为确保您的私有包信息保留在 GitLab 中，请始终确保在运行 npm audit 命令时指定 GitLab 注册表。

已知问题

• 审计结果取决于 包转发 是否启用。如果管理员或组所有者禁用了转发，npm audit 不会返回漏洞信息。
• 审计请求包含您项目中所有包的信息，包括私有包。

支持的 CLI 命令

GitLab npm 存储库支持以下 npm CLI (npm) 和 yarn CLI (`yarn) 命令：

• npm install：安装 npm 包。
• npm publish：将 npm 包发布到注册表。
• npm dist-tag add：为 npm 包添加分发标签。
• npm dist-tag ls：列出包的分发标签。
• npm dist-tag rm：删除分发标签。
• npm ci：直接从您的 package-lock.json 文件安装 npm 包。
• npm view：显示包元数据。
• npm pack：从包创建 tarball。
• npm deprecate：弃用包的版本。
• npm audit：检查项目依赖项中的漏洞。

故障排除

npm 日志显示不正确

您可能会遇到错误：

npm ERR! 完整的运行日志可以在以下位置找到：.npm/_logs/<date>-debug-0

如果日志没有出现在 .npm/_logs/ 目录中，您可以将日志复制到根目录并在那里查看：

  script:
    - npm install --loglevel verbose
    - cp -r /root/.npm/_logs/ .
  artifacts:
    paths:
      - './_logs'

npm 日志作为工件复制到 /root/.npm/_logs/。

npm install 或 yarn 上出现 404 Not Found 错误

使用 CI_JOB_TOKEN 在另一个项目中安装具有依赖项的 npm 包会得到 404 Not Found 错误。您需要使用有权访问该包及其所有依赖项的令牌进行身份验证。

如果包及其依赖项在同一个组的不同项目中，您可以使用 组部署令牌：

//gitlab.example.com/api/v4/packages/npm/:_authToken=<group-token>
@group-scope:registry=https://gitlab.example.com/api/v4/packages/npm/

如果包及其依赖项分布在多个组中，您可以使用具有访问所有组或单个项目的权限的用户的 个人访问令牌：

//gitlab.example.com/api/v4/packages/npm/:_authToken=<personal-access-token>
@group-1:registry=https://gitlab.example.com/api/v4/packages/npm/
@group-2:registry=https://gitlab.example.com/api/v4/packages/npm/

npm publish 目标是默认的 npm 注册表 (registry.npmjs.org)

确保您的包范围在您的 package.json 和 .npmrc 文件中设置一致。

例如，如果您的 GitLab 中的项目名称是 @scope/my-package，那么您的 package.json 文件应该如下所示：

{
  "name": "@scope/my-package"
}

而 .npmrc 文件应该如下所示：

@scope:registry=https://your_domain_name/api/v4/projects/your_project_id/packages/npm/
//your_domain_name/api/v4/projects/your_project_id/packages/npm/:_authToken="${NPM_TOKEN}"

npm install 返回 npm ERR! 403 Forbidden

如果您收到此错误，请确保：

• 项目设置中启用了包注册表。尽管包注册表默认启用，但可以 禁用它。
• 您的令牌未过期并且具有适当的权限。
• 在给定范围内不存在同名或同版本的包。
• 作用域包 URL 包含尾部斜杠：
  • 正确：//gitlab.example.com/api/v4/packages/npm/
  • 不正确：//gitlab.example.com/api/v4/packages/npm

npm publish 返回 npm ERR! 400 Bad Request

如果您收到此错误，可能是以下问题之一导致的。

包名称不符合命名约定

您的包名称可能不符合 @scope/package-name 包命名约定。

确保名称完全符合约定，包括大小写。然后尝试再次发布。

包已存在

您的包已发布到同一根命名空间中的另一个项目，因此无法使用相同的名称再次发布。

即使先前发布的包共享相同的名称但版本不同，也是如此。

Package JSON 文件太大

确保您的 package.json 文件不超过 20,000 个字符。