培训
发布 NuGet 包
创建 NuGet 包并拥有 .nupkg 文件后,可以公开或私密地向其他开发人员提供该包。 本文介绍如何通过 nuget.org 全局共享公共包。
你还可以通过以下方式仅向团队或组织提供专用包:在文件共享、专用 NuGet 服务器或第三方存储库(如 myget、ProGet、Nexus 存储库或 Artifactory)上承载专用包。 有关详细信息,请参阅托管自己的 NuGet 源。 若要使用 Azure Artifacts 进行发布,请参阅将包发布到 NuGet.org。
若要在 nuget.org 上发布,请使用 Microsoft 帐户登录 nuget.org,并使用它创建免费的 nuget.org 帐户。 按照“添加新个人帐户”中的说明操作。
拥有帐户后,可以使用 nuget.org Web 门户、dotnet CLI 或 NuGet CLI 4.1.0 或更高版本将包发布到 nuget.org。 还可以通过 Azure Pipelines 发布包。
将包上传到 nuget.org 网站:
在 nuget.org 的顶部菜单中选择“上传”,浏览到计算机上的包,然后选择“打开”。
如果包 ID 已存在于 nuget.org,则会出现错误。 更改项目中的包标识符,重新打包,并重试上传。
如果包名称可用,将打开“验证”部分,可以在其中查看包清单中的元数据。 如果在包中包含自述文件,请选择“预览”以确保所有内容都正确呈现。
若要更改任何元数据,请编辑项目文件或 .nuspec 文件、重新生成、重新创建包,然后再次上传。
当所有信息准备就绪后,选择“提交”按钮。
若要使用命令行将包推送到 nuget.org,可以使用 dotnet.exe
或 nuget.exe
v4.1.0 或更高版本来实现所需的 NuGet 协议。 有关详细信息,请参阅NuGet 协议。
若要使用任一命令行,首先需要从 nuget.org 获取 API 密钥。
登录你的 nuget.org 帐户,或创建一个帐户(如果你还没有帐户)。
选择右上角的用户名,然后选择“API 密钥”。
选择“创建”,为秘钥提供一个名称。
在“选择范围”下,选择“推送”。
在“选择包>”“Glob 模式”下,输入 *。
选择创建。
选择“复制”以复制新秘钥。
重要
- 始终将 API 密钥保留为机密。 API 密钥就像一个密码,允许任何人代表你管理软件包。 如果 API 密钥意外显示,则删除或重新生成密钥。
- 请将密钥保存在安全位置,因为以后无法再次复制密钥。 如果返回到 API 密钥页,则需要重新生成密钥以对其进行复制。 如果你不再希望推送包,还可以删除 API 密钥。
设定范围允许创建针对不同用途的单独 API 密钥。 每个密钥都有过期时间,并且可以将秘钥范围限定为特定包(或 glob 模式)。 还可以将每个密钥限定为特定操作:推送新包和包版本、仅推送新包版本或取消列出。
通过范围限定,可以为管理组织不同包的不同人员创建 API 密钥,这样他们就只具有所需的权限。
有关详细信息,请参阅范围内的 API 密钥。
从包含 .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 的包可能不会保留。
在命令提示符处运行以下命令,将
<your_API_key>
替换为你从 nuget.org 获取的密钥:nuget setApiKey <your_API_key>
此命令将 API 密钥存储在 NuGet 配置中,以便无需在同一台计算机上再次输入 API 秘钥。
备注
此 API 密钥不用于使用专用源进行身份验证。 若要管理用于使用这些源进行身份验证的凭据,请参阅 nuget sources 命令。
使用以下命令推送包:
nuget push YourPackage.nupkg -Source https://api.nuget.org/v3/index.json
作为持续集成/持续部署 (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 的包会经过多次验证,例如病毒检查,并定期扫描现有包。 包通过所有验证检查后,可能需要一些时间才能对包编制索引并将其显示在搜索结果中。 对包编制索引时,它将显示在“未列出的包”下,并在包页面显示以下消息:
验证和编制索引完成后,你将收到一封确认已成功发布包的电子邮件。 如果包未通过验证检查,将更新包页面以显示相关错误,同时你也会收到通知电子邮件。
包验证和编制索引所需的时间通常不超过 15 分钟。 如果包发布时间超过预期,请在 status.nuget.org 检查 nuget.org 状态。如果所有系统都正常运行,并且包未在一小时内成功发布,请使用包页面上的“联系支持”链接联系 nuget.org。
若要查看包状态,请选择 nuget.org 右上角帐户名称下的“管理包”,然后从已发布的包或未列出的包中选择该包。
包所有者均拥有包的完全权限,包括添加和删除其他所有者以及发布更新。
尽管每个 NuGet 包的 .nuspec 文件定义了该包的创建者,但 nuget.org 不使用该元数据定义所有权。 相反,nuget.org 将所有权分配给发布包的人员、上传包的已登录用户,或者向将 dotnet push
、nuget SetApiKey
或 nuget push
与 API 密钥结合使用的用户。
若要更改包的所有权,请执行以下操作:
使用包的当前所有者的帐户登录 nuget.org。
选择右上方的帐户名称,选择“管理包”,然后展开“已发布的包”。
选择要管理的包,然后在包页面右侧选择“管理包”。
在包管理页上,选择“所有者”。
请执行以下一项操作:
选择“删除”,删除当前所有者。
在“添加所有者”下添加所有者,方法是通过输入其用户名和一条消息,然后选择“添加”。
此操作会向该新共有者发送包含确认链接的电子邮件。 确认后,此人拥有添加和删除所有者的完全权限。 确认之前,“当前所有者”部分显示此人的状态为“待审批”。
若要转移所有权(如所有权更改或包在错误的帐户下发布时),请添加新所有者。 确认所有权后,他们可以从列表中删除旧所有者。
若要将所有权分配给公司或组,请使用转发到适当团队成员的电子邮件别名创建 nuget.org 帐户。 例如,各种 Microsoft ASP.NET 包由 microsoft 和 aspnet 帐户共同拥有。
有时,包所有者可能不太活跃。 例如,原所有者可能已离开生产包的公司。 如果你是包的合法所有者且需要重新获得所有权,请使用 nuget.org 上的联系表单向 NuGet 团队解释相关情况。 团队会按照流程来验证所有权,包括尝试查找现有所有者,并可以向你发送成为包所有者的新邀请。