如何使用极狐GitLab 软件包仓库功能托管 npm？

极狐GitLab 是 GitLab 在中国的发行版，关于中文参考文档和资料有：

• 极狐GitLab 中文文档
• 极狐GitLab 中文论坛
• 极狐GitLab 官网

软件包库中的 npm 包 (BASIC ALL)

npm 是 JavaScript 和 Node.js 的默认包管理器。开发者使用 npm 共享和重用代码，管理依赖项和简化项目工作流。在极狐GitLab 中，npm 包在软件开发生命周期中的重要角色。

对于 npm 包管理器客户端使用的特定 API 端点的文档，请参见 npm API 文档。

了解如何构建 npm 或 yarn 包。

对软件包仓库进行认证

您必须对软件包仓库进行认证来发布或安装来自私有项目或私有群组的软件包。如果项目获群组是公开的，则您无需认证。如果项目是内部的，则您必须是极狐GitLab 实例的注册用户。匿名用户无法从内部项目中拉取软件包。

要进行认证，您可以使用：

• 一个具有 api 范围的个人访问令牌。
• 一个具有 read_package_registry 或/和 write_package_registry 范围的部署令牌。
• 一个 CI 作业令牌。

如果您的阻止在使用双因素认证（2FA），您必须使用具有 api 范围的个人访问令牌。如果您通过 CI/CD 流水线发布软件包，则您必须使用 CI 作业令牌。更多详情，可查阅令牌指南。

不要使用文档中未写明的认证方法。未写明的认证方法可能在将来删除。

使用 .npmrc 进行认证

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

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

如果您正安装：

• 从实例：

//your_domain_name/api/v4/packages/npm/:_authToken="${NPM_TOKEN}"

• 从群组：

//your_domain_name/api/v4/groups/your_group_id/-/packages/npm/:_authToken="${NPM_TOKEN}"

• 从项目：

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

在这些示例中：

• 将 your_domain_name 替换为您的域名，例如 gitlab.com。
• 将 your_group_id 替换为您在群组主页中找到的群组 ID。
• 将 your_project_id 替换为您在 项目概览页 中找到的项目 ID。
• 将 your_token 替换为部署令牌，群组访问令牌、项目访问令牌或个人访问令牌。

WARNING:千万不要在 .npmrc 文件中直接硬编码极狐GitLab 令牌（或任何令牌），也不要在可以提交到仓库的任何其他文件中硬编码令牌。

使用 npm config set 进行认证

要这么做：

npm config set -- //your_domain_name/:_authToken=your_token

对于版本 7 及更早版本，使用完整的端点 URL。

如果您正在安装：

• 从实例：

npm config set -- //your_domain_name/api/v4/packages/npm/:_authToken=your_token

• 从群组：

npm config set -- //your_domain_name/api/v4/groups/your_group_id/-/packages/npm/:_authToken=your_token

• 从项目：

npm config set -- //your_domain_name/api/v4/projects/your_project_id/packages/npm/:_authToken=your_token

在这些示例中：

• 将 your_domain_name 替换为您的域名，例如 gitlab.com。
• 将 your_group_id 替换为您在群组主页中找到的群组 ID。
• 将 your_project_id 替换为您在 项目概览页 中找到的项目 ID。
• 将 your_token 替换为部署令牌，群组访问令牌、项目访问令牌或个人访问令牌。

NOTE:在 npm 版本 8 及以后版本中，您可以在 _authToken 参数中使用 URI 片段代替完整 URL。然而，群组特定端点不受支持。

设置仓库 URL

要从极狐GitLab 软件包仓库发布或安装软件包，您需要配置 npm 以正确使用仓库 URL。配置方法和 URL 结构取决于您是否发布或安装软件包。

在配置仓库 URL 之前，了解不同配置方法的范围是非常重要的：

• .npmrc 文件：配置是文件所在文件夹的本地配置。

• npm config set 命令：这将修改全局 npm 配置，并影响在您系统上运行的所有 npm 命令。

• publishConfig 在 package.json 中：此配置仅适用于发布该软件包，只适用于发布该软件包。

WARNING:运行 npm config set 更改全局 npm 配置。此更改影响您的系统上运行的所有 npm 命令，无论当前工作目录是什么。使用此方法时要小心，尤其是在共享系统上。

发布软件包

当发布软件包时，使用项目端点。URL 结构是：

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

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

::Tabs
:::TabTitle .npmrc file
在您的项目根目录下创建或编辑 .npmrc 文件:

@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}"

:::TabTitle npm config
使用 npm config set 命令

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

:::TabTitle package.json
将 publishConfig 部分添加到您的 package.json 中：

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

::EndTabs
用您的软件包范围替换 @scope。

安装软件包

当安装软件包时，您可以使用项目、群组或实例级端点。端点结构会根据不同情况变化：

您可以使用如下之一的方法来配置这些 URL：

当您安装软件包时，您可以使用项目、群组或实例端点。端点结构会根据不同情况变化。要配置这些 URL，使用以下之一的方法：

::Tabs
:::TabTitle .npmrc file

在您项目的根目录下，创建或编辑 .npmrc 文件。根据需要使用适当的 URL：

• 针对项目：

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

• 针对群组：

npm config set @scope:registry=https://gitlab.example.com/api/v4/groups/<group_id>/-/packages/npm/

• 针对实例：

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

:::TabTitle npm config
和适当的 URL 一起使用 npm config set 命令：

• 针对项目：

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

• 针对群组：

npm config set @scope:registry=https://gitlab.example.com/api/v4/groups/<group_id>/-/packages/npm/

• 针对实例：

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

::EndTabs

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

当您配置玩您的仓库 URL 后，参阅认证部分内容进行认证设置。

发布到极狐GitLab 软件包仓库

要将 npm 软件包发布到极狐GitLab 软件包仓库，您必须是被认证的。

命名约定

取决于您安装的软件包，您可能需要遵循命名约定。

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

• 实例：当您有多个 npm 软件包在不同的极狐GitLab 群组或在自己的命名空间中时使用。

• 群组：当您有多个 npm 软件包在不同的项目下，且它们位于相同的群组或子群组时使用。

• 项目：当您有少量的 npm 软件包，它们不在相同的极狐GitLab 群组时使用。

如果您有计划从 项目 或 群组 安装软件包，那么您不必遵循命名约定。

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

• 用于 @scope 的值是托管软件包的项目的根名称，而不是拥有该软件包自身源代码的项目的根名称。作用域名称应该使用小写形式。
• 软件包名称可以是任何您想要的名称

项目 URL	所在的软件包	范围	完整的软件包名称
https://gitlab.com/my-org/engineering-group/analytics	Analytics	@my-org	@my-org/package-name

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

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

通过命令行发布软件包

当您完成认证后，发布软件包：

npm publish

如果您使用 .npmrc 文件进行认证，设置预期环境变量：

NPM_TOKEN=your_token npm publish

您的软件包现在应该发布到了软件包仓库。
如果上传的软件包有多个 package.json 文件，只使用第一个找到的，并忽略其他的。

通过使用 CI/CD 流水线发布软件包

当使用 CI/CD 流水线发布软件包时，您可以使用预定义变量 ${CI_PROJECT_ID} 和 ${CI_JOB_TOKEN} 来使用您项目的软件包仓库进行认证。我们使用这些变量在 CI/CD 流水线执行时创建 .npmrc 文件来进行认证。

WARNING:当生成 .npmrc 文件时，不要在 ${CI_SERVER_HOST} 后指定默认端口，例如 80 或 443。

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

default:image: node:lateststages:- deploypublish-npm:stage: deployscript:- 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 项目、群组或实例安装软件包：

• 实例：在您有许多 npm 包在不同的极狐GitLab 群组或在自己的命名空间中时使用。

• 群组：在您有许多项目在同一极狐GitLab 群组中时使用。

• 项目：在您有少量软件包，它们不在同一个极狐GitLab 群组中时使用。

从实例安装

WARNING:要从实例安装软件包，软件包必须遵循命名约定来发布。

1.对软件包仓库进行认证。

2.设置仓库：

npm config set @scope:registry https://your_domain_name.com/api/v4/packages/npm/

• 将 @scope 替换为您要从其安装软件包的项目的根级别群组。
• 将 your_domain_name 替换为您的域名，例如 gitlab.com。
• 将 your_token 替换为部署令牌，群组访问令牌、项目访问令牌或个人访问令牌。

3.安装软件包：

npm install @scope/my-package

从群组安装

• 引入于极狐GitLab 16.0，使用名为 npm_group_level_endpoints 的功能标志。默认禁用。
• 在极狐GitLab 16.1 中 GA，功能标志 npm_group_level_endpoints 被移除。

1.对软件包仓库进行认证。

2.设置仓库：

npm config set @scope:registry=https://your_domain_name/api/v4/groups/your_group_id/-/packages/npm/

• 将 @scope 替换为您要从其安装软件包的项目的根级别群组。
• 将 your_domain_name 替换为您的域名，例如 gitlab.com。
• 将 your_group_id 替换为您的群组 ID，可以在群组的主页中找到。

3.安装软件包：

npm install @scope/my-package

从项目安装

1.对软件包仓库进行认证。

2.设置仓库：

npm config set @scope:registry=https://your_domain_name/api/v4/projects/your_project_id/packages/npm/

• 将 @scope 替换为您要从其安装软件包的项目的根级别群组。
• 将 your_domain_name 替换为您的域名，例如 gitlab.com。
• 将 your_project_id 替换为您在 项目概览页 中找到的项目 ID。

3.安装软件包

npm install @scope/my-package

软件包转发至 npmjs.com

• 引入于极狐GitLab 12.9。
• 在 GitLab 17.0 中，角色从维护者更改为所有者。

当在软件包仓库中未找到 npm 软件包时，极狐GitLab 将响应 HTTP 重定向，以便请求客户端可以重新发送请求到 npmjs.com。

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

群组所有者可以在群组的 软件包和仓库 设置中禁用此行为。

弃用一个软件包

• 引入于极狐GitLab 16.0。

您可以弃用一个软件包以便在获取该软件包时显示弃用警告。
先决条件：

• 和删除软件包相同的权限。

• 对软件包仓库进行认证。

从命令行中，运行：

npm deprecate @scope/package "Deprecation message"

CLI 还可以接受 @scope/package 的版本范围。比如：

npm deprecate @scope/package "All package versions are deprecated"
npm deprecate @scope/package@1.0.1 "Only version 1.0.1 is deprecated"
npm deprecate @scope/package@"< 1.0.5" "All package versions less than 1.0.5 are deprecated"

移除弃用警告

要移除软件包弃用警告，请为消息指定空字符串（空字符串）。比如：

npm deprecate @scope/package ""

使用小贴士

从其他组织安装 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               # Publish a package with new tag
npm dist-tag add @scope/package@version my-tag # Add a tag to an existing package
npm dist-tag ls @scope/package                 # List all tags under the package
npm dist-tag rm @scope/package@version my-tag  # Delete a tag from the package
npm install @scope/package@my-tag              # Install a specific tag

从 CI/CD

• 引入于极狐GitLab 15.10。

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

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 6.9.0 的一个 bug，删除分发标签失败。确保您的 npm 版本是 6.9.1 或更高版本。

支持的 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 日志显示不正确

您可能会遇到如下错误：

npm ERR! A complete log of this run can be found in: .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/

WARNING:要小心对待个人访问令牌。阅读我们的令牌安全考量来管理个人访问令牌（例如，设置短期到期日期和使用最小范围）。

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 软件包命名约定。
确保名称符合约定，包括大小写。然后再次尝试发布。

软件包已存在

您的软件包已经发不到了相同 root 命名空间下的其他项目中，因此无法使用相同的名称再次发布。
即使之前发布的软件包名称相同，但版本不同，也是如此。

软件包 JSON 文件过大

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