软件包仓库中的 NuGet 软件包

在您的项目的软件包仓库中发布 NuGet 软件包。然后，当您需要将它们用作依赖项时安装软件包。

软件包仓库与以下工具一起工作：

• NuGet CLI
• .NET Core CLI
• Visual Studio

要了解这些客户端使用的特定 API 端点，请参阅 NuGet API 参考。

了解如何 安装 NuGet。

认证到软件包仓库#

您需要身份验证令牌才能访问极狐GitLab 软件包仓库。根据您要实现的目标，可以使用不同的令牌。有关更多信息，请查看 令牌指南。

• 如果您的组织使用双重身份验证 (2FA)，您必须使用将作用域设置为 api 的 个人访问令牌。
• 如果您通过 CI/CD 流水线发布软件包，可以使用具有私有 runner 的 CI/CD 作业令牌。您还可以 注册变量 用于实例 runner。

使用极狐GitLab 的 NuGet 软件包端点#

您可以使用项目或群组端点与极狐GitLab 软件包仓库进行交互：

• 项目端点：当您有一些不在同一群组中的 NuGet 软件包时使用。
• 群组端点：当您有许多不同项目下的 NuGet 软件包时使用。

某些操作，如发布软件包，仅在项目端点上可用。

由于 NuGet 处理凭证的方式，软件包仓库拒绝对公共群组的匿名请求。

添加软件包仓库作为 NuGet 软件包的来源#

要发布和安装软件包到软件包仓库，您必须将软件包仓库添加为您的软件包来源。

先决条件：

• 您的极狐GitLab 用户名
• 身份验证令牌（以下部分假设使用个人访问令牌）
• 您来源的名称
• 项目或群组 ID

使用项目端点#

shell
nuget source Add -Name <source_name> -Source "https://gitlab.example.com/api/v4/projects/<project_id>/packages/nuget/index.json" -UserName <gitlab_username> -Password <personal_access_token>

shell
nuget source Add -Name "GitLab" -Source "https://gitlab.example.com/api/v4/projects/10/packages/nuget/index.json" -UserName carol -Password <your_access_token>

shell
dotnet nuget add source "https://gitlab.example.com/api/v4/projects/<project_id>/packages/nuget/index.json" --name <source_name> --username <gitlab_username> --password <personal_access_token>

shell
dotnet nuget add source "https://gitlab.example.com/api/v4/projects/10/packages/nuget/index.json" --name gitlab --username carol --password <your_access_token> --store-password-in-clear-text

shell
choco source add -n=<source_name> -s "'https://gitlab.example.com/api/v4/projects/<project_id>/packages/nuget/v2'" -u=<gitlab_username> -p=<personal_access_token>

shell
choco source add -n=gitlab -s "'https://gitlab.example.com/api/v4/projects/10/packages/nuget/v2'" -u=carol -p=<your_access_token>

使用群组端点#

shell
nuget source Add -Name <source_name> -Source "https://gitlab.example.com/api/v4/groups/<group_id>/-/packages/nuget/index.json" -UserName <gitlab_username> -Password <personal_access_token>

shell
nuget source Add -Name "GitLab" -Source "https://gitlab.example.com/api/v4/groups/23/-/packages/nuget/index.json" -UserName carol -Password <your_access_token>

shell
dotnet nuget add source "https://gitlab.example.com/api/v4/groups/<group_id>/-/packages/nuget/index.json" --name <source_name> --username <gitlab_username> --password <personal_access_token>

shell
dotnet nuget add source "https://gitlab.example.com/api/v4/groups/23/-/packages/nuget/index.json" --name gitlab --username carol --password <your_access_token> --store-password-in-clear-text

发布软件包#

先决条件：

• 将软件包仓库设置为 来源。
• 配置 极狐GitLab 项目端点用于 NuGet 软件包。

发布软件包时：

• 查看您的极狐GitLab 实例的最大文件大小限制：
  • 极狐GitLab.com 实例上的软件包仓库限制因文件格式而异，无法配置。
  • 极狐GitLab 私有化部署实例上的软件包仓库限制因文件格式而异，可以配置。
• 如果允许重复，并且您多次发布相同版本的同一软件包，则每次连续上传都会保存为单独的文件。安装软件包时，极狐GitLab 提供最新的文件。
• 大多数上传的软件包应立即在 软件包仓库 页面上可见。少数软件包可能需要最多 10 分钟才能在后台处理后可见。

使用 NuGet CLI#

先决条件：

• 使用 NuGet CLI 创建的 NuGet 软件包。

要发布软件包，请运行以下命令：

shell
nuget push <package_file> -Source <source_name>

替换：

• <package_file> 为您的软件包文件名，以 .nupkg 结尾。
• <source_name> 为您的来源名称。

例如：

shell
nuget push MyPackage.1.0.0.nupkg -Source gitlab

使用 .NET CLI#

先决条件：

• 使用 .NET CLI 创建的 NuGet 软件包。

要发布软件包，请运行以下命令：

shell
dotnet nuget push <package_file> --source <source_name>

替换：

• <package_file> 为您的软件包文件名，以 .nupkg 结尾。
• <source_name> 为您的来源名称。

例如：

shell
dotnet nuget push MyPackage.1.0.0.nupkg --source gitlab

您可以使用 --api-key 选项而不是 username 和 password 发布软件包：

shell
dotnet nuget push <package_file> --source <source_url> --api-key <personal_access_token>

替换：

• <package_file> 为您的软件包文件名，以 .nupkg 结尾。
• <source_url> 为 NuGet 软件包仓库的 URL。

例如：

shell
dotnet nuget push MyPackage.1.0.0.nupkg --source https://gitlab.example.com/api/v4/projects/<project_id>/packages/nuget/index.json --api-key <personal_access_token>

使用 Chocolatey CLI#

先决条件：

• 使用 项目端点的来源。

要使用 Chocolatey CLI 发布软件包，运行以下命令：

shell
choco push <package_file> --source <source_url> --api-key <gitlab_personal_access_token, deploy_token or job token>

替换：

• <package_file> 为您的软件包文件名，以 .nupkg 结尾。
• <source_url> 为 NuGet v2 源软件包仓库的 URL。

例如：

shell
choco push MyPackage.1.0.0.nupkg --source "https://gitlab.example.com/api/v4/projects/<project_id>/packages/nuget/v2" --api-key <personal_access_token>

使用 CI/CD 流水线#

如果您使用极狐GitLab CI/CD 发布 NuGet 软件包，您可以使用 CI_JOB_TOKEN 预定义变量而不是个人访问令牌或部署令牌。作业令牌继承生成流水线的用户或成员的权限。

以下部分中的示例解决了使用 CI/CD 流水线时常见的 NuGet 发布工作流程。

在默认分支更新时发布软件包#

要在每次更新 main 分支时发布新软件包：

1. 在项目的 .gitlab-ci.yml 文件中，添加以下 deploy 作业：

   yaml
   1default:
   2  # 更新到更当前的 SDK 版本
   3  image: mcr.microsoft.com/dotnet/sdk:7.0
   4
   5stages:
   6  - deploy
   7
   8deploy:
   9  stage: deploy
   10  script:
   11    # 在 Release 配置中构建软件包
   12    - dotnet pack -c Release
   13    # 配置极狐GitLab 软件包仓库作为 NuGet 来源
   14    - dotnet nuget add source "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/nuget/index.json" --name gitlab --username gitlab-ci-token --password $CI_JOB_TOKEN --store-password-in-clear-text
   15    # 将软件包推送到项目的软件包仓库
   16    - dotnet nuget push "bin/Release/*.nupkg" --source gitlab
   17  rules:
   18    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH  # 仅在主分支上运行
   19  environment: production

2. 提交更改并推送到您的极狐GitLab 仓库以触发新的 CI/CD 构建。

使用 Git 标签发布版本化软件包#

要使用 Git 标签发布版本化 NuGet 软件包：

1. 在项目的 .gitlab-ci.yml 文件中，添加以下 deploy 作业：

   yaml
   1publish-tagged-version:
   2  stage: deploy
   3  script:
   4    # 使用 Git 标签作为软件包版本
   5    - dotnet pack -c Release /p:Version=${CI_COMMIT_TAG} /p:PackageVersion=${CI_COMMIT_TAG}
   6    # 配置极狐GitLab 软件包仓库作为 NuGet 来源
   7    - dotnet nuget add source "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/nuget/index.json" --name gitlab --username gitlab-ci-token --password $CI_JOB_TOKEN --store-password-in-clear-text
   8    # 将软件包推送到项目的软件包仓库
   9    - dotnet nuget push "bin/Release/*.nupkg" --source gitlab
   10  rules:
   11    - if: $CI_COMMIT_TAG  # 仅在推送标签时运行

2. 提交更改并推送到您的极狐GitLab 仓库。

3. 推送 Git 标签以触发新的 CI/CD 构建。

根据不同环境有条件发布软件包#

您可以配置 CI/CD 流水线，以根据您的用例有条件地发布 NuGet 软件包到不同环境。

要有条件地发布 NuGet 软件包到 development 和 production 环境：

1. 在项目的 .gitlab-ci.yml 文件中，添加以下 deploy 作业：

   yaml
   1  # 发布开发/预览软件包
   2publish-dev:
   3  stage: deploy
   4  script:
   5    # 使用流水线 ID 创建开发版本以确保唯一性
   6    - VERSION="0.0.1-dev.${CI_PIPELINE_IID}"
   7    - dotnet pack -c Release /p:Version=$VERSION /p:PackageVersion=$VERSION
   8    # 配置极狐GitLab 软件包仓库作为 NuGet 来源
   9    - dotnet nuget add source "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/nuget/index.json" --name gitlab --username gitlab-ci-token --password $CI_JOB_TOKEN --store-password-in-clear-text
   10    # 将软件包推送到项目的软件包仓库
   11    - dotnet nuget push "bin/Release/*.nupkg" --source gitlab
   12  rules:
   13    - if: $CI_COMMIT_BRANCH == "develop"
   14  environment: development
   15
   16  # 发布稳定版软件包
   17publish-release:
   18  stage: deploy
   19  script:
   20    - dotnet pack -c Release
   21    # 配置极狐GitLab 软件包仓库作为 NuGet 来源
   22    - dotnet nuget add source "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/nuget/index.json" --name gitlab --username gitlab-ci-token --password $CI_JOB_TOKEN --store-password-in-clear-text
   23    # 将软件包推送到项目的软件包仓库
   24    - dotnet nuget push "bin/Release/*.nupkg" --source gitlab
   25  rules:
   26    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
   27  environment: production

2. 提交更改并推送到您的极狐GitLab 仓库。

   使用此 CI/CD 配置：

   • 将 NuGet 软件包推送到 develop 分支会将软件包发布到您的 development 环境的软件包仓库。
   • 将 NuGet 软件包推送到 main 分支会将 NuGet 软件包发布到您的 production 环境的软件包仓库。

关闭重复的 NuGet 软件包#

您可以发布具有相同名称和版本的多个软件包。

要阻止群组成员和用户发布重复的 NuGet 软件包，请关闭 允许重复 设置：

1. 在左侧边栏，选择 搜索或转到 并找到您的群组。
2. 选择 设置 > 软件包和仓库。
3. 在 重复软件包 表的 NuGet 行中，关闭 允许重复 切换。
4. 可选。在 例外 文本框中，输入匹配允许的软件包名称和版本的正则表达式。

您还可以使用 GraphQL API中的 nuget_duplicates_allowed 设置关闭重复的 NuGet 软件包。

安装软件包#

极狐GitLab 软件包仓库可以包含多个具有相同名称和版本的软件包。如果您安装重复的软件包，检索到的是最近发布的软件包。

先决条件：

• 将软件包仓库设置为 来源。
• 配置 极狐GitLab 的 NuGet 软件包端点。

从命令行#

shell
nuget install <package_id> -OutputDirectory <output_directory> \
  -Version <package_version> \
  -Source <source_name>

shell
dotnet add package <package_id> \
       -v <package_version>

使用 NuGet v2 源#

先决条件：

• Chocolatey 的 v2 源。
• 安装或升级软件包时必须提供软件包版本。

要使用 Chocolatey CLI 安装软件包：

shell
choco install <package_id> -Source <source_url> -Version <package_version>

• <package_id>：软件包 ID。
• <source_url>：NuGet v2 源软件包仓库的 URL 或名称。
• <package_version>：软件包版本。

例如：

shell
choco install MyPackage -Source gitlab -Version 1.0.2

# 或

choco install MyPackage -Source "https://gitlab.example.com/api/v4/projects/<project_id>/packages/nuget/v2" -u <username> -p <personal_access_token> -Version 1.0.2

要使用 Chocolatey CLI 升级软件包：

shell
choco upgrade <package_id> -Source <source_url> -Version <package_version>

• <package_id>：软件包 ID。
• <source_url>：NuGet v2 源软件包仓库的 URL 或名称。
• <package_version>：软件包版本。

例如：

shell
choco upgrade MyPackage -Source gitlab -Version 1.0.3

删除软件包#

先决条件：

• 您必须在项目中拥有 维护者角色或更高权限。
• 您必须同时拥有软件包名称和版本。

要使用 NuGet CLI 删除软件包：

shell
nuget delete <package_id> <package_version> -Source <source_name> -ApiKey <personal_access_token>

• <package_id>：软件包 ID。
• <package_version>：软件包版本。
• <source_name>：来源名称。

例如：

shell
nuget delete MyPackage 1.0.0 -Source gitlab -ApiKey <personal_access_token>

符号软件包#

极狐GitLab 可以从 NuGet 软件包仓库消费符号文件。您可以使用极狐GitLab 软件包仓库作为符号服务器来调试您的 NuGet 软件包。

每当您发布一个 NuGet 软件包文件 (.nupkg) 时，符号软件包文件 (.snupkg) 会自动上传到 NuGet 软件包仓库。

您也可以手动推送它们：

shell
nuget push My.Package.snupkg -Source <source_name>

使用极狐GitLab 的符号文件端点#

极狐GitLab 软件包仓库提供一个特殊的 symbolfiles 端点，您可以使用项目或群组端点进行配置：

• 项目端点：

  plaintext
  https://gitlab.example.com/api/v4/projects/<project_id>/packages/nuget/symbolfiles

  • 替换 <project_id> 为项目 ID。

• 群组端点：

  plaintext
  https://gitlab.example.com/api/v4/groups/<group_id>/-/packages/nuget/symbolfiles

  • 替换 <group_id> 为群组 ID。

symbolfiles 端点是一个配置的调试器可以推送符号文件的来源。

使用软件包仓库作为符号服务器#

要使用符号服务器：

1. 使用 GraphQL API启用 nuget_symbol_server_enabled 命名空间设置。
2. 配置您的调试器以使用符号服务器。

例如，要将 Visual Studio 配置为您的调试器：

1. 选择 工具 > 偏好设置。
2. 选择 调试器 > 符号来源。
3. 选择 添加。
4. 输入符号服务器 URL。
5. 选择 添加来源。

配置调试器后，您可以按通常方式调试您的应用程序。如果符号 PDB 文件可用，调试器会自动从软件包仓库下载。

消费符号软件包#

当调试器配置为消费符号软件包时，调试器在请求中发送以下信息：

• Symbolchecksum 标头：符号文件的 SHA-256 校验和。
• file_name 请求参数：符号文件的名称。例如，mypackage.pdb。
• signature 请求参数：PDB 文件的 GUID 和年龄。

极狐GitLab 服务器匹配这些信息到符号文件并返回它。

请记住：

• 仅支持便携式 PDB 文件。
• 因为调试器无法提供身份验证令牌，符号服务器端点不支持典型的身份验证方法。极狐GitLab 服务器需要 signature 和 Symbolchecksum 来返回正确的符号文件。

支持的 CLI 命令#

极狐GitLab NuGet 仓库支持 NuGet CLI (nuget) 和 .NET CLI (dotnet) 的以下命令：

故障排除#

在处理 NuGet 软件包时，您可能会遇到以下问题。

清除 NuGet 缓存#

为了提高性能，NuGet 缓存软件包文件。如果您遇到存储问题，请使用以下命令清除缓存：

shell
nuget locals all -clear

在基于 Docker 的极狐GitLab 安装中发布 NuGet 软件包时出现错误#

发布 NuGet 软件包时，您可能会收到以下错误消息：

• Error publishing
• Invalid Package: Failed metadata extraction error

阻止了对本地网络地址的 Webhook 请求，以防止对内部 Web 服务的利用。

要解决这些错误，请更改您的网络设置以 允许 Webhook 和集成请求到本地网络。