將您的資訊清單提交至存放庫

發行項
10/05/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 (英文)，然後按一下 [Fork] (分叉)。
在 Windows 命令提示字元或 PowerShell 中，使用下列命令複製您的分叉。
```
git clone <your-fork-name>
```
如果您要輸入多項提交項目，請建立一個分支 (branch)，而不是分叉 (fork)。我們目前只允許每次提交一個資訊清單檔案。
```
git checkout -b <branch-name>
```

步驟 4：將您的資訊清單新增至本機存放庫

您必須將資訊清單檔案新增至採用下列資料夾結構的存放庫：

資訊清單 / 字母 / 發行者 / 應用程式 / 版本

[資訊清單] 資料夾是存放庫中所有資訊清單的根資料夾。
[字母] 資料夾是小寫發行者名稱中的第一個字母。例如，發行者 Microsoft 的 m。
[發行者] 資料夾是發行軟體的公司名稱。例如 Microsoft。
[應用程式] 資料夾是應用程式或工具的名稱。例如 VSCode。
[版本] 資料夾是應用程式或工具的版本，例如 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 並建立提取要求，以將您的分叉 (fork) 或分支 (branch) 合併至主要分支。

screenshot of pull request tab

提交程序

您建立提取要求後，系統會啟動自動化程序以驗證資訊清單和您的提取要求。在這個程序中，我們會對安裝程式和已安裝的二進位檔執行測試，以驗證提交項目。

我們會將標籤新增至您的提取要求，以便您追蹤進度。如需標籤及其程序的詳細資訊，請參閱下方的提取要求標籤一節。

程序完成後，仲裁者會手動審查您的提交項目。獲得核准後，您的應用程式就會新增至 Windows 封裝管理員目錄。

如果在程序中發生錯誤，您會收到通知，而我們的標籤和 Bot 將協助您修正提交項目。如需常見錯誤的清單，請參閱下方的「驗證程序」一節。

驗證程序

您建立提取要求將資訊清單提交給 Windows 封裝管理員存放庫後，系統會啟動自動化程序以驗證資訊清單並處理您的提取要求。 GitHub 標籤可用於分享進度，以及讓您與我們溝通。

提交的預期結果

所有提交至 Windows 封裝管理員存放庫的應用程式提交項目都必須遵守 Windows 封裝管理員存放庫原則。

提交項目的預期結果：

資訊清單會符合結構描述需求。
資訊清單中的所有 URL 都會導向安全網站。
安裝程式和應用程式都沒有病毒。此套件可能會被誤認為惡意程式碼。如果您認為這是誤判，可以將安裝程式提交給 Microsoft Defender小組進行分析 (英文)。
應用程式會為系統管理員和非系統管理員進行正確地安裝和卸載。
安裝程式支援非互動模式。
所有資訊清單項目都是正確的，不會產生誤導。
安裝程式直接來自發行者的網站。

如需原則的完整清單，請參閱 Windows 封裝管理員原則。

提取要求標籤

在驗證期間，我們會將一系列標籤套用至提取要求 (英文)，以傳達進度狀況。有些標籤會指示您採取行動，有些標籤則會導向 Windows 封裝管理員工程小組。

狀態標籤

下表旨在說明您可能看到的狀態標籤。

標籤	詳細資料
Azure-Pipeline-Passed	資訊清單已完成測試階段，正在等待核准。如果在測試階段沒有遇到任何問題，系統會自動核准資訊清單。假使測試失敗，資訊清單會被加上須手動審查的標幟。
Blocking-Issue	出現此標籤代表無法核准提取要求，因為發生執行問題。您通常可以透過包含的錯誤標籤判斷是哪種執行問題。
Needs-Attention	出現此標籤代表提取要求需要由 Windows 封裝管理員開發小組進行調查，若不是因為測試失敗需要手動審查，就是因為社群對提取要求新增了留言。
Needs-Author-Feedback	提交項目失敗，我們會將提取要求重新指派給您。如果您未在 10 天內解決這個問題，Bot 就會關閉提取要求。當應該更新的提取要求失敗，或者提取要求的審查人員有疑問時，通常會新增 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 個警告] 連結。
在下一個頁面上，選取失敗的作業。
下一頁會顯示失敗作業的輸出，這應該可協助您識別修正資訊清單需要進行的變更。

以下示例顯示在安裝驗證工作期間發生的錯誤。