使用 NuGet 注册表

对 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 工作流中使用 GITHUB_TOKEN 删除或恢复软件包（通过 REST API），前提是该令牌对软件包拥有 admin 权限。使用工作流发布软件包的仓库，以及您已显式连接到软件包的仓库，都会自动获得该仓库中软件包的 admin 权限。

有关 GITHUB_TOKEN 的更多信息，请参阅 在工作流中使用 GITHUB_TOKEN 进行身份验证。有关在 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 API 进行身份验证。创建个人访问令牌（经典版）时，可根据需要为令牌分配不同的范围。有关个人访问令牌（经典版）的软件包相关范围的更多信息，请参阅 GitHub Packages 权限概述。

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

• GITHUB_TOKEN 来发布与工作流仓库关联的软件包。
• 使用至少具备 read:packages 范围的个人访问令牌（经典版）来安装与其他私有仓库关联的软件包（如果仓库被授予读取软件包的权限，也可以使用 GITHUB_TOKEN。参见 配置软件包的访问控制和可见性）。

您必须使用具备相应范围的个人访问令牌（经典版）来在 GitHub Packages 中发布和安装软件包。更多信息请参阅 GitHub Packages 入门。

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

您必须替换

• 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 账户的个人访问令牌，请参阅 管理个人访问令牌。

1. 创建一个新项目。将 PROJECT_NAME 替换为您想为项目起的名称。

   dotnet new console --name PROJECT_NAME
   

2. 打包项目。

   dotnet pack --configuration Release
   

3. 使用个人访问令牌作为 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 文档中的 创建并发布包。

1. 对 GitHub Packages 进行身份验证。更多信息请参阅 对 GitHub Packages 进行身份验证。

2. 创建一个新项目。将 PROJECT_NAME 替换为您想为项目起的名称。

   dotnet new console --name PROJECT_NAME
   

3. 将项目的特定信息添加到以 .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>
   

4. 打包项目。

   dotnet pack --configuration Release
   

5. 使用您在 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 包。

1. 对 GitHub Packages 进行身份验证。更多信息请参阅 对 GitHub Packages 进行身份验证。

2. 要使用包，请在 .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>
   

3. 使用 restore 命令安装这些包。

   dotnet restore
   

故障排除

如果您在 GitHub Actions 工作流中使用 GITHUB_TOKEN 对 GitHub Packages 注册表进行身份验证，则该令牌无法访问工作流所在仓库之外的私有基于仓库的包。要访问其他仓库关联的包，请改为生成具有 read:packages 范围的个人访问令牌（经典版），并将该令牌作为 secret 传入。

恢复公共包时出现间歇性 403 错误

如果您在同时使用 GitHub Packages 和 nuget.org，并在恢复标准公共包（如 Microsoft.Extensions.*）时遇到间歇性 403 Forbidden 错误，这可能是因为 NuGet 会对每个包查询所有已配置的包源。当 GitHub Packages 的身份验证临时失败时，会阻塞整个恢复过程，即使是那些不在 GitHub Packages 上的包也会受到影响。

为避免此问题，请使用 NuGet 包源映射将包路由到特定源。

将以下内容替换为

• NAMESPACE 为拥有您 GitHub Packages NuGet 源的个人账户或组织的名称。
• PACKAGE-ID-PREFIX 为您在 GitHub Packages 上托管的包使用的 NuGet 包 ID 前缀。如果使用多个前缀，请为每个前缀添加额外的 <package> 条目。

<configuration>
    <packageSources>
        <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
        <add key="github" value="https://nuget.pkg.github.com/NAMESPACE/index.json" />
    </packageSources>
    <packageSourceMapping>
        <packageSource key="nuget.org">
            <package pattern="*" />
        </packageSource>
        <packageSource key="github">
            <package pattern="PACKAGE-ID-PREFIX.*" />
        </packageSource>
    </packageSourceMapping>
</configuration>

NuGet 使用 最具体的匹配模式：匹配 PACKAGE-ID-PREFIX.* 的包仅从 GitHub Packages 获取，而所有其它包则从 nuget.org 获取。这还能通过确保私有包只能来自您的 GitHub Packages 源来帮助防止依赖混淆攻击。

延伸阅读

• 删除和恢复软件包