使用 NuGet 注册表

您可以配置 `dotnet` 命令行界面 (CLI) 以将 NuGet 包发布到 GitHub Packages，并使用存储在 GitHub Packages 上的包作为 .NET 项目中的依赖项。

谁可以使用此功能？

GitHub Packages 可用于 GitHub 免费版、GitHub 专业版、组织的 GitHub 免费版、GitHub 团队版、GitHub Enterprise Cloud 和 GitHub Enterprise Server 3.0 或更高版本。

使用旧版按存储库付费计划的帐户不提供对私有存储库的 GitHub Packages 支持。此外，使用旧版按存储库付费计划的帐户无法访问支持细粒度权限的注册表，因为这些帐户按存储库计费。有关支持细粒度权限的注册表列表，请参阅“GitHub Packages 的权限”。有关更多信息，请参阅“GitHub 的计划”。

本文内容

对 GitHub Packages 进行身份验证

GitHub Packages 仅支持使用个人访问令牌（经典版）进行身份验证。有关更多信息，请参阅“管理您的个人访问令牌”。

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

您可以使用个人访问令牌（经典版）对 GitHub Packages 或 GitHub API 进行身份验证。创建个人访问令牌（经典版）时，您可以根据需要为令牌分配不同的作用域。有关个人访问令牌（经典版）的与包相关的范围的更多信息，请参阅“GitHub Packages 的权限”。

要在 GitHub Actions 工作流中对 GitHub Packages 注册表进行身份验证，您可以使用

`GITHUB_TOKEN` 发布与工作流存储库关联的包。
具有至少 `read:packages` 作用域的个人访问令牌（经典版）来安装与其他私有存储库关联的包（`GITHUB_TOKEN` 无法访问）。

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

此注册表支持细粒度权限。对于支持细粒度权限的注册表，如果您的 GitHub Actions 工作流正在使用个人访问令牌对注册表进行身份验证，我们强烈建议您更新工作流以使用 `GITHUB_TOKEN`。有关更新使用个人访问令牌对注册表进行身份验证的工作流的指导，请参阅“使用 GitHub Actions 发布和安装包”。

注意

GitHub Actions 工作流使用 REST API 删除和恢复包的功能目前处于公开预览阶段，可能会有所更改。

如果令牌对包具有 `admin` 权限，则可以在 GitHub Actions 工作流中使用 `GITHUB_TOKEN` 使用 REST API 删除或恢复包。使用工作流发布包的存储库以及您已明确连接到包的存储库会自动获得对存储库中包的 `admin` 权限。

有关 `GITHUB_TOKEN` 的更多信息，请参阅“自动令牌身份验证”。有关在 Actions 中使用注册表的最佳实践的更多信息，请参阅“GitHub Actions 的安全加固”。

使用以下命令在 GitHub Actions 工作流中使用 `GITHUB_TOKEN` 对 GitHub Packages 进行身份验证，而不是在存储库的 nuget.config 文件中硬编码个人访问令牌

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` 替换为您关联包的个人帐户或组织的名称。

将 `USERNAME` 替换为连接到已验证源时要使用的用户名。

您还可以选择分别为 GitHub Codespaces 和 GitHub Actions 提供对包的访问权限。有关更多信息，请参阅“配置包的访问控制和可见性”和“配置包的访问控制和可见性”。

使用个人访问令牌进行身份验证

GitHub Packages 仅支持使用个人访问令牌（经典版）进行身份验证。有关更多信息，请参阅“管理您的个人访问令牌”。

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

您可以使用个人访问令牌（经典版）对 GitHub Packages 或 GitHub API 进行身份验证。创建个人访问令牌（经典版）时，您可以根据需要为令牌分配不同的作用域。有关个人访问令牌（经典版）的与包相关的范围的更多信息，请参阅“GitHub Packages 的权限”。

要在 GitHub Actions 工作流中对 GitHub Packages 注册表进行身份验证，您可以使用

`GITHUB_TOKEN` 发布与工作流存储库关联的包。
具有至少 `read:packages` 作用域的个人访问令牌（经典版）来安装与其他私有存储库关联的包（`GITHUB_TOKEN` 无法访问）。

您必须使用具有相应作用域的个人访问令牌（经典版）才能在 GitHub Packages 中发布和安装包。有关更多信息，请参阅“GitHub Packages 简介”。

要使用 `dotnet` 命令行界面 (CLI) 对 GitHub Packages 进行身份验证，请在项目目录中创建一个 *nuget.config* 文件，在 `packageSources` 下为 `dotnet` CLI 客户端指定 GitHub Packages 作为源。

您必须替换

`USERNAME` 为您在 GitHub 上的个人帐户名称。
`TOKEN` 为您的个人访问令牌（经典版）。
`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* 文件进行身份验证、使用 `--api-key` 命令行选项和您的 GitHub 个人访问令牌（经典版）或使用可以直接从命令行使用 `dotnet` 命令行界面 (CLI) 运行的命令来将包发布到 GitHub Packages。

将 `OWNER` 替换为您的用户名或公司名称，将 `YOUR_GITHUB_PAT` 替换为您的个人访问令牌。

dotnet nuget add source --username OWNER --password YOUR_GITHUB_PAT --store-password-in-clear-text --name github "https://nuget.pkg.github.com/OWNER/index.json"

NuGet 注册表将包存储在您的组织或个人帐户中，并允许您将包与代码库关联。您可以选择继承代码库的权限，也可以独立于代码库设置细粒度的权限。

首次发布包时，默认可见性为私有。要更改可见性或设置访问权限，请参阅“配置包的访问控制和可见性”。有关将已发布的包与代码库关联的更多信息，请参阅“将代码库连接到包”。

如果在项目的 .csproj 文件中指定了RepositoryURL，则发布的包将自动连接到指定的代码库。有关更多信息，请参阅“使用 NuGet 注册表”。有关将已发布的包链接到代码库的信息，请参阅“将代码库连接到包”。

使用 GitHub 个人访问令牌作为 API 密钥发布包

如果您还没有用于 GitHub 帐户的个人访问令牌，请参阅“管理您的个人访问令牌”。

创建一个新项目。将PROJECT_NAME替换为您想要给项目起的名字。
```
dotnet new console --name PROJECT_NAME
```
打包项目。
```
dotnet pack --configuration Release
```
使用您的个人访问令牌作为 API 密钥发布包。将PROJECT_NAME替换为项目名称，将1.0.0替换为包的版本号，并将YOUR_GITHUB_PAT替换为您的个人访问令牌。
```
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”。

要使用包，请添加ItemGroup并在 .csproj 项目文件中配置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作用域的个人访问令牌（经典版），并将此令牌作为机密传入。

进一步阅读

“删除和恢复包”