MSIX 故障排除指南

本指南涵蓋安裝、簽約、App 安裝程式交付、缺少相依性及執行時行為中最常見的 MSIX 錯誤。 每個部分都包含症狀、根本原因及解決方法。

若要查看完整的部署事件日誌，請開啟事件檢視器並導覽至：Applications and Services Logs → Microsoft → Windows → AppxDeployment-Server → Operational

安裝錯誤

0x80070005 — 存取被拒絕

症狀： Add-AppxPackage 或應用程式安裝程式因錯誤代碼 0x80070005失敗。

適用於：Windows 10及後期Windows 11

原因與解決方法：

套件安裝被阻擋，因為應用程式正在使用中

症狀：更新或重新安裝失敗，並出現錯誤提示該套件正在使用中。 在 事件檢視器 中，你會看到部署操作被拒絕。

適用於：Windows 10及後期Windows 11

解決方法：更新前關閉所有執行中的應用程式實例。 如果該應用程式是背景服務或有註冊的背景任務，你可能也需要終止這些任務：

Get-Process -Name "MyApp" | Stop-Process -Force
Add-AppxPackage -Path .\updated-app.msix

企業部署時，建議使用 Intune 或 設定管理員 在維護期間排程更新。

最低版本或架構不匹配

Symptom：安裝失敗，錯誤訊息為「該套件無法安裝，因為它與此版本的 Windows 不相容」或「該套件不適用於此機器」。

適用於：Windows 10及之後

原因與解決方法：

Add-AppxPackage 成功了，但開始選單裡的應用程式卻不見了

症狀：PowerShell 報告成功，但應用程式不會出現在開始功能表或應用程式清單中。

適用於：Windows 10及後期Windows 11

常見原因：

• 按使用者安裝與按機器安裝Add-AppxPackage：僅為目前使用者安裝。 如果你是以管理員身份執行，但需要為其他使用者使用此應用程式，請改用 Add-AppxProvisionedPackage。
• 套件已註冊但磁貼未釘選：應用程式已安裝，但開始選單尚未重新整理。 請登出再登入，或在應用程式 設定→ 確認安裝。
• 清單中缺少「開始選單」項目：確認<Application>中的AppxManifest.xml元素包含一個有效的VisualElements項目，以及Square150x150Logo。
• 重複套件族名稱衝突：如果已安裝的應用程式存在相同套件族名稱的新版或舊版，新的安裝可能會不動聲色地取代它。 請檢查 Get-AppxPackage -Name "YourPackageFamilyName"。

簽署與憑證錯誤

憑證不被信任（0x800B0109）

症狀：安裝失敗且出錯 0x800B0109 ——「憑證鏈已處理，但終止於不被信任提供者信任的根憑證中。」

適用於：Windows 10及後期Windows 11

原因：用於簽署封裝的憑證不在裝置的受信任憑證儲存庫中。 這在使用自簽憑證進行開發時很常見。

解決方法：將簽署憑證匯入裝置的 本地電腦→可信使用者 儲存庫（非目前使用者儲存庫——應用程式安裝程式只檢查機器儲存庫）：

# Export the certificate from the package first (if needed)
$cert = (Get-AuthenticodeSignature -FilePath .\app.msix).SignerCertificate
Export-Certificate -Cert $cert -FilePath .\app-cert.cer

# Import into Trusted People (requires administrator rights)
Import-Certificate -FilePath .\app-cert.cer -CertStoreLocation Cert:\LocalMachine\TrustedPeople

對於生產應用程式，請使用由受信任的 CA 或 Azure Artifact Signing（前稱 Trusted Signing） 發出的憑證，這些憑證會連結到 Microsoft 身份驗證根憑證授權機構（Identity Verification Root Certificate Authority）——該憑證在 1809 版及以後版本Windows 10 Windows 11 預設受信任。

Publisher名稱不符（0x8007000B，事件ID 150）

Symptom：SignTool 在 0x8007000B 時失敗，且 事件檢視器（AppxPackagingOM 操作日誌）顯示 Event ID 150：

error 0x8007000B: The app manifest publisher name (CN=Contoso) must match
the subject name of the signing certificate (CN=Contoso, C=US).

適用於：Windows 10及後期Windows 11

Cause： 中的 屬性必須與簽章憑證的 主體名稱完全一致——包括所有可分辨名稱欄位，且順序需相同。

修正：

1. 從證書上取得確切的科目名稱：

   (Get-Item Cert:\CurrentUser\My\THUMBPRINT).Subject
   # Example output: CN=Contoso, C=US
   

2. 更新 AppxManifest.xml 使其完全匹配：

   <Identity Name="Contoso.MyApp"
             Publisher="CN=Contoso, C=US"
             ... />
   

3. 重新包裝 MakeAppx.exe 並重新簽署。

應用程式安裝程式與網頁傳遞錯誤

.appinstaller 檔案中的結構版本不符

症狀：App Installer 無法解析或處理檔案， .appinstaller 常出現關於無效檔案或不支援結構的通用錯誤。

適用於：Windows 10及以後版本（依版本而定 — 見表）

Cause：Uri根元素的 <AppInstaller> 屬性指定了已安裝版本 Windows 不支援的結構版本。

Schema 版本依Windows版本分類：

解決方法：將檔案 .appinstaller 中的結構 URI 設定為你最低支援作業系統所需的最低版本：

<?xml version="1.0" encoding="utf-8"?>
<AppInstaller Uri="https://example.com/app.appinstaller"
              Version="1.0.0.0"
              xmlns="http://schemas.microsoft.com/appx/appinstaller/2017">

如果你需要支援較舊的 Windows 10 版本，請避免使用最新的 schema 版本。

檔案提供錯誤的 MIME 類型或缺少內容長度

症狀：從 HTTP/HTTPS 端點安裝應用程式安裝程式失敗。 錯誤可能是通用的，例如 0x80072F76 「未知錯誤」或「應用程式安裝失敗」。

適用於：Windows 10及之後

原因：網頁伺服器提供的.msix、.msixbundle或.appinstaller檔案有錯誤的Content-Type標頭，或省略了Content-Length標頭。

解決方法：設定您的網頁伺服器以提供正確的 MIME 類型的 MSIX 相關檔案：

同時確保每個回應都包含有效的Content-Length標頭——這適用於GET請求和HEAD請求。

對於 IIS，請在 web.config 中加入 MIME 類型的映射。 對於 Azure Static Web Apps 或 GitHub Pages，這些擴充的 MIME 類型可能需要明確設定或自訂主機解決方案。

遺漏相依性

未安裝框架套件（VCLibs、.NET、Windows 應用程式 SDK）

Symptom：應用程式安裝成功，但啟動時當機，或安裝失敗，並出現依賴性錯誤，該錯誤涉及套件族名，如 Microsoft.VCLibs、Microsoft.WindowsAppRuntime 或 Microsoft.NET.Native。

適用於：Windows 10及後期Windows 11

常見框架及其取得途徑：

開發修正：在本地安裝 Add-AppxPackage 時，添加 -DependencyPackages 參數或預先安裝框架套件：

# Install VCLibs dependency first
Add-AppxPackage -Path .\Microsoft.VCLibs.x64.14.00.Desktop.appx

# Then install your app
Add-AppxPackage -Path .\MyApp.msix

發行修正：如果是在商店外發佈，請在您的 .appinstaller 檔案中 <Dependencies>包含框架套件：

<Dependencies>
  <Package Name="Microsoft.VCLibs.140.00.UWPDesktop"
           Publisher="CN=Microsoft Corporation, O=Microsoft Corporation, L=Redmond, S=Washington, C=US"
           Version="14.0.30704.0"
           Uri="https://aka.ms/Microsoft.VCLibs.x64.14.00.Desktop.appx"
           ProcessorArchitecture="x64"/>
</Dependencies>

CI/CD 中找不到 SignTool

Symptom：CI/CD 管線（GitHub Actions、Azure DevOps）會因錯誤失敗，錯誤如 'signtool' is not recognized as an internal or external command 或 SignTool.exe: not found。

適用於：Windows 10及之後，Windows 11（簽名機）

Cause：SignTool 是 Windows SDK 的一部分，預設不包含在標準 CI 執行器映像中。

Fixes:

選項1 — 在管道中安裝 Windows SDK （GitHub Actions）：

- name: Install Windows SDK
  run: |
    winget install --id Microsoft.WindowsSDK.10.0.22621 --accept-source-agreements --accept-package-agreements

選項二 — 使用 WinApp CLI （MSIX 簽名最簡單）：

- name: Install WinApp CLI
  run: winget install -e --id Microsoft.WinAppCLI --source winget --accept-source-agreements
- name: Sign MSIX
  run: winapp sign output\MyApp.msix --cert ${{ secrets.CERT_THUMBPRINT }}

選項3 — 使用Azure Artifact Signing（建議用於生產環境）：

- name: Sign with Azure Artifact Signing
  uses: azure/trusted-signing-action@v0
  with:
    azure-tenant-id: ${{ secrets.AZURE_TENANT_ID }}
    azure-client-id: ${{ secrets.AZURE_CLIENT_ID }}
    azure-client-secret: ${{ secrets.AZURE_CLIENT_SECRET }}
    endpoint: ${{ secrets.AZURE_ARTIFACT_SIGNING_ENDPOINT }}
    trusted-signing-account-name: ${{ secrets.AZURE_CODE_SIGNING_NAME }}
    certificate-profile-name: ${{ secrets.AZURE_CERT_PROFILE_NAME }}
    files-folder: ${{ github.workspace }}\output
    files-folder-filter: msix

欲了解 CI/CD 簽章設定的完整流程，請參閱 「簽署你的 MSIX 套件 - 端對端指南」。

執行時與虛擬化行為

MSIX 套件運行於輕量級應用程式容器中。 有些看似錯誤的行為其實是設計使然——容器會攔截檔案和登錄檔操作以保護系統其他部分。

為什麼檔案寫入似乎會消失（VFS 檔案導向）

症狀：應用程式會在執行時寫入一個檔案到路徑 C:\Program Files\MyApp\config.ini ，但該檔案並未出現在該路徑上。 App 會正確讀取數值，但其他流程或使用者卻看不到。

適用於：Windows 10及後期Windows 11

說明：MSIX 使用 虛擬檔案系統（VFS） 重定向。 寫入受保護系統路徑時會靜默地重新導向到每個使用者的容器：

%LocalAppData%\Packages\<PackageFamilyName>\LocalCache\Local\VFS\

這是設計上的——它防止 MSIX 應用程式修改共享系統位置，支援乾淨卸載。

選項：

• 改用應用程式資料夾：將資料寫入 ApplicationData.Current.LocalFolder（WinRT）或 %LocalAppData%\Packages\<PFN>\LocalState\，以確保每位使用者的資料會持續存在。
• 使用 AppData\Roaming 以便資料可以在不同裝置間漫遊。
• 檢查 VFS 容器以查看重定向檔案：%LocalAppData%\Packages\<PackageFamilyName>\LocalCache\

若要了解哪些路徑是虛擬化的，請參閱 MSIX 容器中的執行時問題故障排除。

為什麼登錄檔寫入似乎消失了（登錄檔虛擬化）

症狀：應用程式在執行期間會寫入HKEY_LOCAL_MACHINE\Software\MyApp\，但該值對其他進程不可見，或在重新安裝後不會保留。

適用於：Windows 10及後期Windows 11

說明：MSIX 攔截寫入 HKLM\Software 並將它們重新導向到一個與系統其他部分隔離的每個套件登錄箱。 卸載後，蜂巢會被刪除。

選項：

• 將每個使用者設定寫入 HKEY_CURRENT_USER\Software\<AppName> ——這些 設定未 被虛擬化且持續存在。
• 使用 Windows ApplicationData APIS 來儲存結構化設定。
• 宣告必須在使用者或程序間共享的登錄檔條目，使用 AppxManifest.xml<Extensions> / <com:Extension> 機制。

想深入了解 MSIX 容器的行為，請參見 了解打包桌面應用程式如何在 Windows 上執行。

Windows 10 MSIX 限制

部分 MSIX 功能需要 Windows 11 或特定的 Windows 10 版本。 如果你要部署到 Windows 10 裝置，請注意以下幾點。

需要 Windows 10、2004 版本（版本 19041）或更新版本的功能

需要 Windows 11 的功能

版本 1709 之前的 Windows 10 裝置

MSIX 在 1709 之前的 Windows 10 版本（秋季創作者更新）中不原生支援。 要將 MSIX 套件部署到這些裝置，請使用 MSIX Core，該套件為低階 Windows 10 版本提供相容層。

清單檔擴充

部分 AppxManifest.xml 命名空間擴充僅支援 Windows 11。 在針對 Windows 10 的套件中宣告這些功能，可能會在封裝過程中結構驗證失敗，或在安裝時被拒絕。 請查看每個擴充套件列出的應用程式封裝資訊清單架構參考MinOSVersion。

除錯技巧

要確認特定 Windows 10 版本中可用的 MSIX 功能，請參考 MSIX 功能與支援平台頁面，該頁面列出依作業系統版本提供的功能可用性。

相關資源

• MSIX 套件簽署概覽
• 簽署你的 MSIX 套件 - 完整指南
• SignTool 已知問題與故障排除
• 故障排除應用程式安裝程式問題
• 在 MSIX 容器中排除執行時問題
• 排解 Windows 應用程式的封裝、部署與查詢功能