发布 NuGet 包

创建 NuGet 包并拥有 .nupkg 文件后,可以公开或私密地向其他开发人员提供该包。 本文介绍如何通过 nuget.org 全局共享公共包。

你还可以通过以下方式仅向团队或组织提供专用包:在文件共享、专用 NuGet 服务器或第三方存储库(如 myget、ProGet、Nexus 存储库或 Artifactory)上承载专用包。 有关详细信息,请参阅托管自己的 NuGet 源。 若要使用 Azure Artifacts 进行发布,请参阅将包发布到 NuGet.org

发布到 nuget.org

若要在 nuget.org 上发布,请使用 Microsoft 帐户登录 nuget.org,并使用它创建免费的 nuget.org 帐户。 按照“添加新个人帐户”中的说明操作。

Screenshot that shows the NuGet sign in link.

拥有帐户后,可以使用 nuget.org Web 门户、dotnet CLI 或 NuGet CLI 4.1.0 或更高版本将包发布到 nuget.org。 还可以通过 Azure Pipelines 发布包。

上传到 nuget.org Web 门户

将包上传到 nuget.org 网站:

  1. 在 nuget.org 的顶部菜单中选择“上传”,浏览到计算机上的包,然后选择“打开”。

    Screenshot that shows the Upload dialog on nuget.org

    如果包 ID 已存在于 nuget.org,则会出现错误。 更改项目中的包标识符,重新打包,并重试上传。

  2. 如果包名称可用,将打开“验证”部分,可以在其中查看包清单中的元数据。 如果在包中包含自述文件,请选择“预览”以确保所有内容都正确呈现。

    若要更改任何元数据,请编辑项目文件或 .nuspec 文件、重新生成、重新创建包,然后再次上传。

  3. 当所有信息准备就绪后,选择“提交”按钮。

使用命令行推送

若要使用命令行将包推送到 nuget.org,可以使用 dotnet.exenuget.exe v4.1.0 或更高版本来实现所需的 NuGet 协议。 有关详细信息,请参阅NuGet 协议

若要使用任一命令行,首先需要从 nuget.org 获取 API 密钥。

创建 API 密钥

  1. 登录你的 nuget.org 帐户,或创建一个帐户(如果你还没有帐户)。

  2. 选择右上角的用户名,然后选择“API 密钥”。

  3. 选择“创建”,为秘钥提供一个名称。

  4. 在“选择范围”下,选择“推送”。

  5. 在“选择包>”“Glob 模式”下,输入 *。

  6. 选择创建

  7. 选择“复制”以复制新秘钥。

    Screenshot that shows the new API key with the Copy link.

重要

  • 始终将 API 密钥保留为机密。 API 密钥就像一个密码,允许任何人代表你管理软件包。 如果 API 密钥意外显示,则删除或重新生成密钥。
  • 请将密钥保存在安全位置,因为以后无法再次复制密钥。 如果返回到 API 密钥页,则需要重新生成密钥以对其进行复制。 如果你不再希望推送包,还可以删除 API 密钥。

设定范围允许创建针对不同用途的单独 API 密钥。 每个密钥都有过期时间,并且可以将秘钥范围限定为特定包(或 glob 模式)。 还可以将每个密钥限定为特定操作:推送新包和包版本、仅推送新包版本或取消列出。

通过范围限定,可以为管理组织不同包的不同人员创建 API 密钥,这样他们就只具有所需的权限。

有关详细信息,请参阅范围内的 API 密钥

使用 dotnet CLI:

从包含 .nupkg 文件的文件夹运行以下命令。 指定 .nupkg 文件名,并将密钥值替换为 API 密钥。

dotnet nuget push Contoso.08.28.22.001.Test.1.0.0.nupkg --api-key qz2jga8pl3dvn2akksyquwcs9ygggg4exypy3bhxy6w6x6 --source https://api.nuget.org/v3/index.json

输出会显示发布流程的结果:

Pushing Contoso.08.28.22.001.Test.1.0.0.nupkg to 'https://www.nuget.org/api/v2/package'...
  PUT https://www.nuget.org/api/v2/package/
warn : All published packages should have license information specified. Learn more: https://aka.ms/nuget/authoring-best-practices#licensing.
  Created https://www.nuget.org/api/v2/package/ 1221ms
Your package was pushed.

有关详细信息,请查看 dotnet nuget push

注意

如果要避免测试包在 nuget.org 上实时运行,可以推送到 https://int.nugettest.org 上的 nuget.org 测试站点。请注意,上载到 int.nugettest.org 的包可能不会保留。

使用 NuGet CLI

  1. 在命令提示符处运行以下命令,将 <your_API_key> 替换为你从 nuget.org 获取的密钥:

    nuget setApiKey <your_API_key>
    

    此命令将 API 密钥存储在 NuGet 配置中,以便无需在同一台计算机上再次输入 API 秘钥。

    注意

    此 API 密钥不用于使用专用源进行身份验证。 若要管理用于使用这些源进行身份验证的凭据,请参阅 nuget sources 命令

  2. 使用以下命令推送包:

    nuget push YourPackage.nupkg -Source https://api.nuget.org/v3/index.json
    

使用 Azure Pipelines 发布

作为持续集成/持续部署 (CI/CD) 流程的一部分,你可以使用 Azure Pipelines 将包推送到 nuget.org。 有关详细信息,请参阅使用 Azure Pipelines 发布 NuGet 包

发布已签名的包

若要提交已签名的包,必须首先注册用于签名包的证书。 如果不满足签名包要求,nuget.org 会拒绝此包。

包大小限制:

Nuget.org 包大小限制约为 250 MB。 上传超出该限制的包时,将显示以下错误:

包文件超出大小限制。 请重试。

如果从命令行推送此类包,则会生成以下输出:

  RequestEntityTooLarge https://www.nuget.org/api/v2/package/ 13903ms
error: Response status code does not indicate success: 413 (The package file exceeds the size limit. Please try again.).

如果收到此错误,请考虑修改包内容以减小其大小。 如果要将调试符号打包到包中,请考虑单独发布它们。 其他资产可以单独发布为一个或多个依赖项包,从而将它们分散到较小的区块中。

包验证和编制索引

推送到 nuget.org 的包会经过多次验证,例如病毒检查,并定期扫描现有包。 包通过所有验证检查后,可能需要一些时间才能对包编制索引并将其显示在搜索结果中。 对包编制索引时,它将显示在“未列出的包”下,并在包页面显示以下消息:

Screenshot of a message indicating that a package isn't yet published.

验证和编制索引完成后,你将收到一封确认已成功发布包的电子邮件。 如果包未通过验证检查,将更新包页面以显示相关错误,同时你也会收到通知电子邮件。

包验证和编制索引所需的时间通常不超过 15 分钟。 如果包发布时间超过预期,请在 status.nuget.org 检查 nuget.org 状态。如果所有系统都正常运行,并且包未在一小时内成功发布,请使用包页面上的“联系支持”链接联系 nuget.org。

若要查看包状态,请选择 nuget.org 右上角帐户名称下的“管理包”,然后从已发布的包未列出的包中选择该包。

在 nuget.org 上管理包所有者

包所有者均拥有包的完全权限,包括添加和删除其他所有者以及发布更新。

尽管每个 NuGet 包的 .nuspec 文件定义了该包的创建者,但 nuget.org 不使用该元数据定义所有权。 相反,nuget.org 将所有权分配给发布包的人员、上传包的已登录用户,或者向将 dotnet pushnuget SetApiKeynuget push 与 API 密钥结合使用的用户。

若要更改包的所有权,请执行以下操作:

  1. 使用包的当前所有者的帐户登录 nuget.org。

  2. 选择右上方的帐户名称,选择“管理包”,然后展开“已发布的包”。

  3. 选择要管理的包,然后在包页面右侧选择“管理包”。

  4. 在包管理页上,选择“所有者”。

  5. 请执行以下一项操作:

    • 选择“删除”,删除当前所有者。

    • 在“添加所有者”下添加所有者,方法是通过输入其用户名和一条消息,然后选择“添加”。

      此操作会向该新共有者发送包含确认链接的电子邮件。 确认后,此人拥有添加和删除所有者的完全权限。 确认之前,“当前所有者”部分显示此人的状态为“待审批”。

若要转移所有权(如所有权更改或包在错误的帐户下发布时),请添加新所有者。 确认所有权后,他们可以从列表中删除旧所有者。

若要将所有权分配给公司或组,请使用转发到适当团队成员的电子邮件别名创建 nuget.org 帐户。 例如,各种 Microsoft ASP.NET 包由 microsoftaspnet 帐户共同拥有。

有时,包所有者可能不太活跃。 例如,原所有者可能已离开生产包的公司。 如果你是包的合法所有者且需要重新获得所有权,请使用 nuget.org 上的联系表单向 NuGet 团队解释相关情况。 团队会按照流程来验证所有权,包括尝试查找现有所有者,并可以向你发送成为包所有者的新邀请。

后续步骤