使用 NuGet 注册表

本文内容

你可以配置 dotnet 命令行接口 (CLI) 以将 NuGet 包发布到 GitHub Packages 并将存储在 GitHub Packages 上的包用作 .NET 项目中的依赖项。

GitHub Packages 适用于 GitHub Free、GitHub Pro、面向组织的 GitHub Free、GitHub Team、GitHub Enterprise Cloud、GitHub Enterprise Server 3.0 或更高版本以及 GitHub AE。
GitHub Packages 不适用于使用旧版按仓库计划的帐户所拥有的私有仓库。此外，使用旧版按存储库计划的帐户无法访问支持精细权限的注册表，因为这些帐户按存储库计费。有关支持精细权限的注册表的列表，请参阅“关于 GitHub Packages 的权限”。有关详细信息，请参阅“GitHub 的计划”。

向 GitHub Packages 验证

GitHub Packages 仅支持使用 personal access token (classic) 进行身份验证。有关详细信息，请参阅“管理个人访问令牌”。

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

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

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

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

在 GitHub Actions 工作流中进行身份验证

此注册表支持精细权限。对于支持精细权限的注册表，如果 GitHub Actions 工作流使用 personal access token 向注册表进行身份验证，则强烈建议更新工作流以使用 GITHUB_TOKEN。有关如何更新通过 personal access token 向注册表进行身份验证的工作流的指南，请参阅“使用 GitHub Actions 发布和安装包”。

注意：GitHub Actions 工作流使用 REST API 删除和还原包的功能目前提供公共 beta 版本，可能会发生更改。

如果令牌具有对包的 admin 权限，你可以在 GitHub Actions 工作流中使用 GITHUB_TOKEN，通过 REST API 来删除或还原包。使用工作流发布包的存储库，以及已经显式连接到包的存储库，会自动获得对存储库中包的 admin 权限。

有关 GITHUB_TOKEN 的详细信息，请参阅“自动令牌身份验证”。有关在操作中使用注册表时的最佳做法的详细信息，请参阅“GitHub Actions 的安全强化”。

在 GitHub Actions 工作流中通过以下命令使用 GITHUB_TOKEN 向 GitHub Packages 进行身份验证，而不是对存储库的 nuget.config 文件中的 personal access token 进行硬编码：

dotnet nuget add source --username USERNAME --password ${{ secrets.GITHUB_TOKEN }} --store-password-in-clear-text --name github "https://nuget.pkg.github.com/NAMESPACE/index.json"

将 NAMESPACE 替换为作为包限定范围的个人帐户或组织的名称。

还可以选择为 GitHub Codespaces 和 GitHub Actions 单独授予对包的访问权限。有关详细信息，请参阅“配置包的访问控制和可见性”和“配置包的访问控制和可见性”。

使用 personal access token 进行身份验证

GitHub Packages 仅支持使用 personal access token (classic) 进行身份验证。有关详细信息，请参阅“管理个人访问令牌”。

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

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

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

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

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

要使用 dotnet 命令行接口 (CLI) 向 GitHub Packages 进行身份验证，请在项目目录中创建一个 nuget.config 文件，将 GitHub Packages 指定为 dotnet CLI 客户端的 packageSources 下的源。

必须：

将 USERNAME 替换为 GitHub 上的个人帐户的名称。
将 TOKEN 替换为 personal access token (classic)。
将 NAMESPACE 替换为作为包限定范围的个人帐户或组织的名称。

<?xml version="1.0" encoding="utf-8"?>
<configuration>
    <packageSources>
        <clear />
        <add key="github" value="https://nuget.pkg.github.com/NAMESPACE/index.json" />
    </packageSources>
    <packageSourceCredentials>
        <github>
            <add key="Username" value="USERNAME" />
            <add key="ClearTextPassword" value="TOKEN" />
        </github>
    </packageSourceCredentials>
</configuration>

发布包

可通过使用 nuget.config 文件进行身份验证或使用包含 GitHub personal access token (classic) 的 --api-key 命令行选项，向 GitHub Packages 发布包。

NuGet 注册表将包存储在组织或个人帐户中，并支持将包与存储库关联。可以选择是从存储库继承权限，还是独立于存储库设置精细权限。

首次发布包时，默认可见性是私有的。要更改可见性或设置访问权限，请参阅“配置包的访问控制和可见性”。有关将已发布的包与存储库链接的详细信息，请参阅“将仓库连接到包”。

如果在 nuget.config 文件中指定 RepositoryURL，则发布的包将自动连接到指定的存储库。有关详细信息，请参阅“使用 NuGet 注册表”。有关将已发布的包链接到存储库的信息，请参阅“将仓库连接到包”。

使用 GitHub personal access token 作为 API 密钥发布包

如果还没有用于 GitHub.com 上帐户的 personal access token，请参阅“管理个人访问令牌”。

创建新项目。将 PROJECT_NAME 替换为要为项目指定的名称。
```
dotnet new console --name PROJECT_NAME
```
打包项目。
```
dotnet pack --configuration Release
```
使用 personal access token 作为 API 密钥发布包。将 PROJECT_NAME 替换为项目名称，将 1.0.0 替换为包的版本号，并将 YOUR_GITHUB_PAT 替换为 personal access token。
```
dotnet nuget push "bin/Release/PROJECT_NAME.1.0.0.nupkg"  --api-key YOUR_GITHUB_PAT --source "github"
```

在发布包后，您可以在 GitHub 上查看该包。有关详细信息，请参阅“查看包”。

使用 nuget.config 文件发布包

发布时，如果你要将包链接到存储库，.csproj 文件中指定的存储库的 OWNER 必须与 nuget.config 身份验证文件中使用的 NAMESPACE 匹配。在 .csproj 文件中指定或递增版本号，然后使用 dotnet pack 命令创建该版本的 .nuspec 文件。有关创建包的详细信息，请参阅 Microsoft 文档中的“创建和发布包”。

注意： 如果发布链接到存储库的包，该包会自动继承链接存储库的访问权限，链接存储库中的 GitHub Actions 工作流会自动获得对包的访问权限，除非你的组织已禁用访问权限的自动继承。有关详细信息，请参阅“配置包的访问控制和可见性”。

向 GitHub Packages 验证。有关详细信息，请参阅“向 GitHub Packages 进行身份验证”。
创建新项目。将 PROJECT_NAME 替换为要为项目指定的名称。
```
dotnet new console --name PROJECT_NAME
```

将项目的特定信息添加到以 .csproj 结尾的项目文件中。请务必将

将 1.0.0 替换为包的版本号。
将 OWNER 替换为拥有你要向其链接包的存储库的个人帐户或组织的名称。
将 REPOSITORY 替换为要将包连接到的存储库的名称。

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>netcoreapp3.0</TargetFramework>
    <PackageId>PROJECT_NAME</PackageId>
    <Version>1.0.0</Version>
    <Authors>AUTHORS</Authors>
    <Company>COMPANY_NAME</Company>
    <PackageDescription>PACKAGE_DESCRIPTION</PackageDescription>
    <RepositoryUrl>https://github.com/OWNER/REPOSITORY</RepositoryUrl>
  </PropertyGroup>

</Project>

打包项目。
```
dotnet pack --configuration Release
```
使用在 nuget.config 文件中指定的 key 发布包。将 PROJECT_NAME 替换为项目名称，并将 1.0.0 替换为包的版本号。
```
dotnet nuget push "bin/Release/PROJECT_NAME.1.0.0.nupkg" --source "github"
```

在发布包后，您可以在 GitHub 上查看该包。有关详细信息，请参阅“查看包”。

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

若要将多个包连接到同一个存储库，可以在所有 .csproj 项目文件的 RepositoryURL 字段中使用同一个 GitHub 存储库 URL。 GitHub 根据该字段匹配仓库。

以下示例将项目 MY_APP 和 MY_OTHER_APP 发布到同一存储库：

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>netcoreapp3.0</TargetFramework>
    <PackageId>MY_APP</PackageId>
    <Version>1.0.0</Version>
    <Authors>Octocat</Authors>
    <Company>GitHub</Company>
    <PackageDescription>This package adds a singing Octocat!</PackageDescription>
    <RepositoryUrl>https://github.com/my-org/my-repo</RepositoryUrl>
  </PropertyGroup>

</Project>

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>netcoreapp3.0</TargetFramework>
    <PackageId>MY_OTHER_APP</PackageId>
    <Version>1.0.0</Version>
    <Authors>Octocat</Authors>
    <Company>GitHub</Company>
    <PackageDescription>This package adds a dancing Octocat!</PackageDescription>
    <RepositoryUrl>https://github.com/my-org/my-repo</RepositoryUrl>
  </PropertyGroup>

</Project>

安装包

在项目中使用来自 GitHub 的包类似于使用来自 nuget.org 的包。将包依赖项添加到 .csproj 文件，并指定包名称和版本。有关在项目中使用 .csproj 文件的详细信息，请参阅 Microsoft 文档中的“使用 NuGet 包”。

向 GitHub Packages 验证。有关详细信息，请参阅“向 GitHub Packages 进行身份验证”。

要使用包，请在 .csproj 项目文件中添加 ItemGroup 并配置 PackageReference 字段。将 Include="PACKAGE_NAME" 中的 PACKAGE_NAME 值替换为包依赖项，并将 Version="X.X.X" 中的 X.X.X 值替换为要使用的包的版本：

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>netcoreapp3.0</TargetFramework>
    <PackageId>My-app</PackageId>
    <Version>1.0.0</Version>
   <Authors>Octocat</Authors>
    <Company>GitHub</Company>
   <PackageDescription>This package adds an Octocat!</PackageDescription>
    <RepositoryUrl>https://github.com/OWNER/REPOSITORY</RepositoryUrl>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="PACKAGE_NAME" Version="X.X.X" />
  </ItemGroup>

</Project>

使用 restore 命令安装包。
```
dotnet restore
```

故障排除

如果使用 GITHUB_TOKEN 对 GitHub Actions 工作流内的 GitHub Packages 注册表进行身份验证，则令牌无法在工作流运行范围以外的其他存储库中访问基于专用存储库的包。若要访问与其他存储库关联的包，请改为生成具有 read:packages 范围的 personal access token (classic)，并将此令牌作为机密传入。

延伸阅读

“删除和恢复包”