将清单提交到存储库

项目
03/27/2023

创建描述应用程序的程序包清单后，即可将清单提交到 Windows 程序包管理器存储库。这是一个面向公众的存储库，其中包含 winget 工具可以访问的清单的集合。若要提交清单，请将其上传到 GitHub 上的开源 https://github.com/microsoft/winget-pkgs 存储库。

通过提交拉取请求将新清单添加到 GitHub 存储库后，一个自动化过程会验证你的清单文件，并通过检查来确保此程序包符合 Windows 程序包管理器策略并且不是已知的恶意程序包。如果验证成功，则会将你的程序包添加到面向公众的 Windows 程序包管理器存储库，以便 winget 客户端工具可以发现它。请注意开源 GitHub 存储库中的清单与面向公众的 Windows 程序包管理器存储库中的清单之间的区别。

重要

Microsoft 保留以任何理由拒绝某个提交的权利。

清单验证

当你将清单提交到 GitHub 上的 https://github.com/microsoft/winget-pkgs 存储库时，系统会自动验证并评估你的清单，以确保 Windows 生态系统的安全。还可以手动查看清单。

有关验证过程的详细信息，请参阅下面的验证过程部分。

如何提交清单

若要将清单提交到存储库，请执行以下步骤。

步骤 1：验证清单

winget 工具提供了 validate 命令来确认是否正确创建了清单。若要验证清单，请使用此命令。

winget validate \<path-to-the-manifests>

如果验证失败，请根据错误来查找行号并进行更正。验证清单后，即可将其提交到存储库。

步骤 2：使用 Windows 沙盒测试清单

Windows 程序包管理器存储库包含一个脚本，用于在沙盒中安装Windows 程序包管理器以测试清单提交。要运行 PowerShell 脚本，请导航到 winget-pkgs 存储库。在 PowerShell 中输入以下命令：

powershell .\Tools\SandboxTest.ps1 manifests\m\Microsoft\VisualStudioCode\1.56.0

可能需要使用清单文件的正确路径更新此脚本：.\Tools\SandboxTest.ps1 <path to manifest or manifest folder>

请参阅 winget-pkgs 存储库中的完整沙盒测试脚本。

步骤 3：克隆存储库

为 Windows 程序包管理器社区存储库创建分支，并将该存储库克隆到本地计算机：

在浏览器中转到 https://github.com/microsoft/winget-pkgs，然后选择“分支”。
在 Windows 命令提示符或 PowerShell 中，使用以下命令克隆分支。
```
git clone <your-fork-name>
```
如果要输入多个提交，请创建一个分支而不是存储库分支。我们目前只允许每次提交一个清单文件。
```
git checkout -b <branch-name>
```

步骤 4：将清单添加到本地存储库

必须将清单文件添加到采用以下文件夹结构的存储库中：

manifests / letter / publisher / application / version

manifests 文件夹是存储库中所有清单的根文件夹。
letter 文件夹是发布者名称的首字母（小写）。例如，发布者“Microsoft”的“m” 。
publisher 文件夹是发布软件的公司的名称。例如，Microsoft。
application 文件夹是应用程序或工具的名称。例如，VSCode。
version 文件夹是应用程序或工具的版本。例如 1.0.0。

清单中的 PackageIdentifier 和 PackageVersion 值必须与清单文件夹路径中的发布者、应用程序名称和版本相匹配。有关详细信息，请参阅创建程序包清单。

步骤 5：将清单提交到远程存储库

你现在已准备就绪，可以将新清单推送到远程存储库了。

使用 commit 命令来添加文件和提交更改，并提供有关此提交的信息。
```
git commit -m "Submitting ContosoApp version 1.0.0" --all
```
使用 push 命令将更改推送到远程存储库。
```
git push
```

步骤 6：创建拉取请求

推送更改后，返回到 https://github.com/microsoft/winget-pkgs 并创建拉取请求，将分叉或分支合并到主分支。

“拉取请求”选项卡的屏幕截图

提交过程

当你创建拉取请求时，会启动一个自动化过程，该过程会验证清单并验证你的拉取请求。在此过程中，我们将针对安装程序和安装的二进制文件运行测试来验证提交情况。

我们会向你的拉取请求添加标签，方便你跟踪其进度。有关标签和过程的详细信息，请参阅下面的拉取请求标签部分。

完成后，提交的内容将由审核员手动审查，在获得批准后，应用程序将添加到 Windows 程序包管理器目录中。

如果在此过程中出现错误，系统会通知你，而且我们的标签和机器人将帮助你解决提交问题。有关常见错误的列表，请参阅下面的验证过程部分。

验证过程

在创建拉取请求以将清单提交到 Windows 程序包管理器存储库时，将启动一个自动化过程，用于验证清单并处理拉取请求。 GitHub 标签用于共享进度，你可以通过它与我们交流。

对提交的预期

提交到 Windows 程序包管理器存储库的所有应用程序都应遵循 Windows 程序包管理器存储库策略。

提交预期：

清单符合架构要求。
清单中的所有 URL 都通向安全的网站。
安装程序和应用程序中没有病毒。程序包可能会被错误地标识为恶意软件。如果你认为这是一个误报，可以将安装程序提交给 Microsoft Defender 团队以便进行分析。
对于管理员和非管理员，应用程序都可以正确地安装和卸载。
安装程序支持非交互模式。
所有清单条目都准确且没有误导性。
安装程序直接来自发布者的网站。

若要查看策略的完整列表，请参阅 Windows 程序包管理器策略。

拉取请求标签

验证过程中会将一系列标签应用于拉取请求以传达进度信息。某些标签将指示你采取措施，而其他标签将送往 Windows 程序包管理器工程团队。

状态标签

下表描述可能出现的状态标签。

标签	详细信息
Azure-Pipeline-Passed	清单已完成测试轮次。正在等待审批。如果在测试轮次中未遇到任何问题，则会自动批准。如果测试失败，可能会标记为需要人工审核。
Blocking-Issue	此标签表示拉取请求因存在阻止问题而无法得到批准。通常可以通过包含的错误标签来判断阻止问题是什么。
Needs-Attention	此标签指示拉取请求需要由 Windows 程序包管理器开发团队进行调查。原因可能是测试失败，需要人工审核，或者是因为社区向拉取请求添加了注释。
Needs-Author-Feedback	指示提交发生故障。我们会将拉取请求重新分配给你。如果你在 10 天内未解决此问题，机器人会关闭拉取请求。通常会在拉取请求发生故障且需要进行更新，或审核该拉取请求的人对该请求有疑问时添加 Needs-Author-Feedback 标签。
Validation-Completed	指示测试轮次已成功完成，并且将合并拉取请求。

错误标签

下表描述可能出现的错误标签。并非所有错误案例都会立即分配给你。有些可能会触发人工验证。

标签	详细信息
Binary-Validation-Error	此拉取请求中包含的应用程序未能通过安装程序扫描测试。此测试旨在确保应用程序能在不发出警告的情况下安装在所有环境中。有关此错误的更多详细信息，请参阅下面的二进制验证错误部分。
Error-Analysis-Timeout	Binary-Validation-Test 测试超时。拉取请求会被分配至 Windows 程序包管理器工程师以进行调查。
Error-Hash-Mismatch	无法处理提交的清单，原因是为 InstallerURL 提供的 InstallerSha256 哈希不匹配。请更新拉取请求中的 InstallerSha256 并重试。
Error-Installer-Availability	验证服务无法下载安装程序。这可能与 Azure IP 范围被阻止有关，或者安装程序 URL 可能不正确。请检查 InstallerURL 是否正确并重试。如果你认为此错误有问题，请添加注释，拉取请求将分配给 Windows 程序包管理器工程师以进行调查。
Manifest-Installer-Validation-Error	在评估 MSIX 包的过程中，清单中存在不一致的情况或值不存在的问题。
Manifest-Path-Error	清单文件必须放入特定的文件夹结构中。此标签表示提交路径存在问题。例如，文件夹结构未采用必需格式。请更新清单和路径以重新提交拉取请求。
Manifest-Validation-Error	提交的清单包含语法错误。请解决清单的语法问题，然后重新提交。有关清单格式和架构的详细信息，请参阅所需的格式。
PullRequest-Error	拉取请求无效，因为并非所有提交的文件都位于清单文件夹下，或者拉取请求中具有多个包或版本。请更新拉取请求以解决该问题，然后重试。
URL-Validation-Error	URL 验证测试找不到 URL 并响应 HTTP 错误状态代码（403 或 404），或是 URL 信誉测试失败。可以通过查看拉取请求检查详细信息来识别哪个 URL 存在问题。若要解决此问题，请更新存在问题的 URL 以解决 HTTP 错误状态代码。如果问题不是由 HTTP 错误状态代码导致，可以提交 URL 以进行审核，从而避免因信誉问题导致的失败。
Validation-Defender-Error	在动态测试期间，Microsoft Defender 报告了问题。若要重现此问题，请安装应用程序，然后运行 Microsoft Defender 完全扫描。如果可以重现此问题，请修复二进制文件或提交以进行分析从而获得误报方面的帮助。如果无法重现问题，请添加注释，让 Windows 程序包管理器工程师进行调查。
Validation-Domain	如果 InstallerURL 与预期的域不匹配，则测试已确定域。此 Windows 程序包管理器策略要求 InstallerUrl 直接来自 ISV 的发布位置。如果你认为这是一个误报检测，请向拉取请求添加注释，让 Windows 程序包管理器工程师进行调查。
Validation-Error	未能在人工批准过程中通过 Windows 程序包管理器验证。查看随附的注释，了解后续步骤。
Validation-Executable-Error	在安装测试期间，测试找不到主应用程序。请确保在所有平台上正确安装应用程序。如果应用程序未安装应用程序，但仍应包含在存储库中，请向拉取请求添加注释，让 Windows 程序包管理器工程师进行调查。
Validation-Hash-Verification-Failed	在安装测试期间，应用程序安装失败，因为 InstallerSha256 与 InstallerURL 哈希不再匹配。如果应用程序在虚 URL 之后，并且安装程序在未更新 InstallerSha256 的情况下进行了更新，则可能会发生这种情况。若要解决此问题，请更新与 InstallerURL 关联的 InstallerSha256，然后再次提交。
Validation-HTTP-Error	用于安装程序的 URL 不使用 HTTPS 协议。请更新 InstallerURL 以使用 HTTPS 并重新提交拉取请求。
Validation-Indirect-URL	该 URL 不直接来自 ISV 服务器。测试已判定使用了重定向程序。不允许这样做，因为 Windows 程序包管理器策略要求 InstallerUrl 直接来自 ISV 的发布位置。请删除重定向并重新提交。
Validation-Installation-Error	在此包的人工验证过程中出现了常规错误。查看随附的注释，了解后续步骤。
Validation-Merge-Conflict	由于合并冲突，无法验证此包。请解决合并冲突并重新提交拉取请求。
Validation-MSIX-Dependency	无法解析的包上存在 MSIX 包的依赖项。请更新包以包含缺少的组件，或将依赖项添加到清单文件并重新提交拉取请求。
Validation-Unapproved-URL	如果 InstallerURL 与预期的域不匹配，则测试已确定域。此 Windows 程序包管理器策略要求 InstallerUrl 直接来自 ISV 的发布位置。
Validation-Unattended-Failed	在安装过程中，测试超时。这很可能是由于应用程序未以无提示方式安装。这也可能是由于遇到其他错误并停止测试。请验证是否能在无需用户输入的情况下安装清单。如果需要帮助，请向拉取请求添加注释，让 Windows 程序包管理器工程师进行调查。
Validation-Uninstall-Error	在卸载测试期间，应用程序在卸载后未完全清理。请查看随附的注释，了解更多详细信息。
Validation-VCRuntime-Dependency	无法解析的 C++ 运行时上存在包的依赖项。请更新包以包含缺少的组件，或将依赖项添加到清单文件并重新提交拉取请求。

内容策略标签

下表列出内容策略标签。如果添加了其中一个标签，则表示清单元数据中的某些内容触发了额外的人工内容审核，目的是确保元数据遵循 Windows 程序包管理器策略。

标签	详细信息
Policy-Test-2.1	请参阅一般内容要求。
Policy-Test-2.2	请参阅内容（包含名称、徽标、原创和第三方）
Policy-Test-2.3	请参阅伤害风险。
Policy-Test-2.4	请参阅诽谤、造谣、诋毁和威胁。
Policy-Test-2.5	请参阅冒犯性内容。
Policy-Test-2.6	请参阅酒精、烟草、武器和毒品。
Policy-Test-2.7	请参阅成人内容。
Policy-Test-2.8	请参阅非法活动。
Policy-Test-2.9	请参阅过度亵渎和不恰当内容。
Policy-Test-2.10	请参阅国家/地区特定的要求。
Policy-Test-2.11	请参阅年龄分级。
Policy-Test-2.12	请参阅用户生成的内容。

内部标签

下表列出内部错误标签。遇到内部错误时，拉取请求将分配给 Windows 程序包管理器工程师以进行调查。

标签	详细信息
Internal-Error-Domain	在 URL 的域验证期间出错。
Internal-Error-Dynamic-Scan	验证已安装的二进制文件时出错。
Internal-Error-Keyword-Policy	验证清单时出错。
Internal-Error-Manifest	验证清单时出错。
Internal-Error-NoArchitectures	因测试无法确定应用程序的体系结构而出现错误。
Internal-Error-NoSupportedArchitectures	因为不支持当前体系结构而出现错误。
Internal-Error-PR	拉取请求的处理过程中出现错误。
Internal-Error-Static-Scan	在安装程序的静态分析过程中出错。
Internal-Error-URL	在安装程序的信誉验证过程中出错。
Internal-Error	在测试轮次中出现一般故障或未知错误。

二进制验证错误

如果拉取请求验证未能通过安装程序扫描测试并收到 Binary-Validation-Error 标签，这意味着应用程序在所有环境中安装失败。

安装程序扫描测试

若要提供出色的应用程序安装用户体验，Windows 程序包管理器必须确保无论环境如何，在电脑上安装所有应用程序时不会出现错误。一项关键测试旨在确保在各种常用的防病毒程序配置上安装所有应用程序时不会发出警告。 Windows 提供了内置的 Microsoft Defender 防病毒程序，但许多企业客户和用户都使用其他防病毒软件。

对 Windows 程序包管理器存储库的每次提交都通过多个防病毒程序运行。这些程序都具有不同的病毒检测算法，用于识别可能不需要的应用程序 (PUA) 和恶意软件。

解决二进制验证错误

如果应用程序验证失败，Microsoft 首先会尝试与防病毒程序供应商验证已标记的软件是否为误报。在许多情况下，在通知和验证后，防病毒程序供应商会更新其算法，然后应用程序就会通过验证。

在某些情况下，防病毒程序供应商无法确定检测到的代码异常是否为误报。在这种情况下，无法将应用程序添加到 Windows 程序包管理器存储库。带有 Binary-Validation-Error 标签的拉取请求被拒绝。

如果拉取请求中带有 Binary-Validation-Error 标签，请更新软件以删除被检测为 PUA 的代码。

有时，用于调试和低级别活动的正版工具会对防病毒软件显示为 PUA。这是因为必要的调试代码与不需要的软件具有相似的签名。虽然此编码做法是合法的，但可惜的是，Windows 程序包管理器存储库不允许这些应用程序。

提交故障排除

如果 Windows 程序包管理器提交失败，可以使用上述标签来调查失败的原因。

要调查拉取请求失败，请执行以下步骤：

拉取请求失败显示在网页底部，带有“有些检查不成功”字符串。选择失败的验证旁边的“详细信息”链接，以转到 Azure Pipelines 页面。
在 Azure Pipelines 页面上，选择“0 个错误/0 个警告”链接。
在下一页上，选择失败的作业。
下一页会显示失败作业的输出。输出应有助于确定修复清单所需的更改。

在下面的示例中，失败是在“安装验证”任务过程中发生的。

通过