包注册表中的 NuGet 包

在你的项目包注册表中发布 NuGet 包。然后在需要使用它们作为依赖项时安装这些包。

包注册表支持以下工具：

• NuGet CLI
• .NET Core CLI
• Visual Studio

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

学习如何安装 NuGet。

向包注册表进行身份验证

你需要一个身份验证令牌才能访问 GitLab 包注册表。根据你的需求，可以使用不同的令牌。更多信息，请查看令牌指南。

• 如果你的组织使用双因素身份验证（2FA），你必须使用一个个人访问令牌，并将范围设置为 api。
• 如果通过 CI/CD 管道发布包，你可以使用CI/CD 作业令牌配合私有 runner。你也可以为实例 runner注册一个变量。

使用 GitLab NuGet 包的端点

你可以使用项目或组端点与 GitLab 包注册表交互：

• 项目端点：当你有几个不在同一组中的 NuGet 包时使用。
• 组端点：当你在同一组的不同项目中有很多 NuGet 包时使用。

某些操作（如发布包）仅在项目端点可用。

由于 NuGet 处理凭据的方式，包注册表会拒绝对公共组的匿名请求。

将包注册表添加为 NuGet 包的源

要发布和安装包到包注册表，你必须将包注册表添加为你的包源。

先决条件：

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

使用项目端点

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>

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

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>

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

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>

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

使用组端点

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>

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

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>

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

发布包

先决条件：

• 将包注册表设置为源。
• 配置 NuGet 包的GitLab 项目端点。

发布包时：

• 查看你的 GitLab 实例的最大文件大小限制：
  • GitLab.com 实例上的包注册表限制因文件格式而异，且不可配置。
  • GitLab 自托管实例上的包注册表限制因文件格式而异，且可配置。
• 如果允许重复，并且你多次发布相同名称和版本的包，每次连续上传都会保存为单独的文件。安装包时，GitLab 会提供最新的文件。
• 大多数上传的包应该立即在包注册表页面中可见。如果某些包需要在后台处理，可能需要最多 10 分钟才能显示。

使用 NuGet CLI

先决条件：

• 使用 NuGet CLI 创建的 NuGet 包。

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

nuget push <package_file> -Source <source_name>

替换：

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

例如：

nuget push MyPackage.1.0.0.nupkg -Source gitlab

使用 .NET CLI

先决条件：

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

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

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

替换：

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

例如：

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

你可以使用 --api-key 选项代替 username 和 password 来发布包：

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

替换：

• <package_file> 为你的包文件名，以 .nupkg 结尾。
• <source_url> 为 NuGet 包注册表的 URL。

例如：

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 发布包，运行以下命令：

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。

例如：

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 作业：

   default:
     # 更新到更当前的 SDK 版本
     image: mcr.microsoft.com/dotnet/sdk:7.0
   
   stages:
     - deploy
   
   deploy:
     stage: deploy
     script:
       # 以 Release 配置构建包
       - dotnet pack -c Release
       # 将 GitLab 包注册表配置为 NuGet 源
       - 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
       # 将包推送到项目的包注册表
       - dotnet nuget push "bin/Release/*.nupkg" --source gitlab
     rules:
       - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH  # 只在 main 分支上运行
     environment: production

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

使用 Git 标签发布版本化包

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

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

   publish-tagged-version:
     stage: deploy
     script:
       # 使用 Git 标签作为包版本
       - dotnet pack -c Release /p:Version=${CI_COMMIT_TAG} /p:PackageVersion=${CI_COMMIT_TAG}
       # 将 GitLab 包注册表配置为 NuGet 源
       - 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
       # 将包推送到项目的包注册表
       - dotnet nuget push "bin/Release/*.nupkg" --source gitlab
     rules:
       - if: $CI_COMMIT_TAG  # 仅在推送标签时运行

2. 提交更改并推送到你的 GitLab 仓库。

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

为不同环境条件发布

你可以配置 CI/CD 管道根据你的用例 有条件地将 NuGet 发布到不同环境。

为 development 和 production 环境有条件地发布 NuGet 包：

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

     # 发布开发/预览包
   publish-dev:
     stage: deploy
     script:
       # 创建具有流水线 ID 的开发版本以确保唯一性
       - VERSION="0.0.1-dev.${CI_PIPELINE_IID}"
       - dotnet pack -c Release /p:Version=$VERSION /p:PackageVersion=$VERSION
       # 将 GitLab 包注册表配置为 NuGet 源
       - 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
       # 将包推送到项目的包注册表
       - dotnet nuget push "bin/Release/*.nupkg" --source gitlab
     rules:
       - if: $CI_COMMIT_BRANCH == "develop"
     environment: development
   
     # 发布稳定发布包
   publish-release:
     stage: deploy
     script:
       - dotnet pack -c Release
       # 将 GitLab 包注册表配置为 NuGet 源
       - 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
       # 将包推送到项目的包注册表
       - dotnet nuget push "bin/Release/*.nupkg" --source gitlab
     rules:
       - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
     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 包注册表可以包含多个具有相同名称和版本的包。 如果你安装重复的包， 将获取最新发布的包。

先决条件：

• 将包注册表设置为源。
• 配置 NuGet 包的GitLab 端点。

从命令行

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

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

使用 NuGet v2 源

先决条件：

• Chocolatey 的v2 源。
• 使用 NuGet v2 源安装或升级包时必须提供包版本。

使用 Chocolatey CLI 安装包：

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

• <package_id>：包 ID。
• <source_url>：NuGet v2 源包注册表的 URL 或名称。
• <package_version>：包版本。

例如：

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 升级包：

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

• <package_id>：包 ID。
• <source_url>：NuGet v2 源包注册表的 URL 或名称。
• <package_version>：包版本。

例如：

choco upgrade MyPackage -Source gitlab -Version 1.0.3

删除包

先决条件：

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

使用 NuGet CLI 删除包：

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

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

例如：

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

符号包

GitLab 可以从 NuGet 包注册表使用符号文件。 你可以使用 GitLab 包注册表作为符号服务器 来调试你的 NuGet 包。

每当发布 NuGet 包文件（.nupkg）时， 符号包文件（.snupkg）会自动 上传到 NuGet 包注册表。

你也可以手动推送它们：

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

使用 GitLab 符号文件端点

GitLab 包注册表提供了一个特殊的 symbolfiles 端点，你可以使用项目或组端点进行配置：

• 项目端点：

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

  • 将 <project_id> 替换为项目 ID。

• 组端点：

  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 会缓存包文件。如果遇到存储问题，使用以下命令清除缓存：

nuget locals all -clear

在基于 Docker 的 GitLab 安装中发布 NuGet 包时出错

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

• Error publishing
• Invalid Package: Failed metadata extraction error

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

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