MSIX 故障排除指南

本指南介绍跨安装、签名、应用安装程序传递、缺少依赖项和运行时行为的最常见 MSIX 错误。每个部分都包含症状、根本原因和解决方法。

有关部署事件的完整日志，请打开事件查看器并导航到：应用和服务日志→ Microsoft → Windows → AppxDeployment-Server →操作

小窍门

对于合并的诊断集，请在分发包之前运行 Windows 应用认证工具包。

安装错误

0x80070005 — 访问被拒绝

症状： Add-AppxPackage 或应用安装程序失败并出现错误代码 0x80070005。

应用到：Windows 10及更高版本，Windows 11

原因和修复：

原因	修复
在需要为每台计算机安装时，以标准用户身份且不提升权限运行软件包。	以管理员身份运行 PowerShell。若要为所有用户安装，请使用 `Add-AppxProvisionedPackage` 而不是 `Add-AppxPackage`。
防病毒或安全软件阻止包文件	暂时禁用实时扫描，或为 `.msix` / `.msixbundle` 文件添加排除项
已为其他用户分配但尚未配置的包	请使用 `Add-AppxProvisionedPackage` 为所有用户进行预配
文件系统 ACL 阻止对包的读取访问	检查 `icacls`包文件的权限;授予对安装用户的读取访问权限

由于应用正在使用，包安装被阻止

症状：更新或重新安装失败，并出现指示包正在使用的错误。在事件查看器中，可以看到部署操作被拒绝。

应用到：Windows 10及更高版本，Windows 11

修复：更新之前关闭应用的所有正在运行的实例。如果应用是后台服务或已注册后台任务，则可能需要终止这些任务：

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

对于企业部署，请考虑使用 Intune 或Configuration Manager在维护时段期间计划更新。

MinVersion 或体系结构不匹配

Symptom：安装失败并出现错误，例如“无法安装包，因为它与此版本的Windows不兼容”或“包不适用于此计算机”。

应用到：Windows 10及更高版本

原因和修复：

原因	修复
清单中的包 `MinVersion` 高于 OS 版本	生成面向已安装 OS 版本的单独包，或更新设备
体系结构不匹配（例如 x64 设备上的 arm64 包）	生成并分发正确的体系结构变体;使用捆绑包（`.msixbundle`）从一个文件中提供多个体系结构
该包面向仅Windows 11 API，但未进行兼容性检查	为Windows 10和Windows 11添加 `TargetDeviceFamily` 条目，或者在运行时使用版本检查保护 API 调用

注释

在分发到混合体系结构环境时使用 .msixbundle 文件。捆绑包包含多个体系结构的包，Windows在安装时选择正确的包。

症状：PowerShell 报告成功，但应用不会显示在“开始”菜单或应用列表中。

应用到：Windows 10及更高版本，Windows 11

常见原因：

按用户与按计算机的安装：Add-AppxPackage 仅为当前用户进行软件安装。如果你以管理员身份运行，但需要其他用户的应用，请改用 Add-AppxProvisionedPackage 。
包已注册但未将磁贴固定到开始菜单：应用已安装，但“开始”菜单未刷新。注销并重新登录，或检查 “设置”→应用 以确认安装。
清单中缺少“开始菜单”条目：请验证<Application> 元素中AppxManifest.xml 包含一个具有有效VisualElements条目的Square150x150Logo。
重复的程序包系列名称冲突：如果已安装具有相同程序包系列名称的较新版本或较旧版本的应用，则新安装可能会以无提示方式替换它。请与Get-AppxPackage -Name "YourPackageFamilyName"进行核对。

签名和证书错误

注释

有关详细的 SignTool 错误代码和标志，请参阅 SignTool 的已知问题和故障排除。

证书不受信任（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，否则不要将签名证书导入 受信任的根证书颁发机构 存储中。导入不受信任的自签名证书会削弱设备的安全态势。

对于生产应用，请使用由受信任的 CA 或 Azure 工件签名（前称可信签名）颁发的证书，该证书链接到 Microsoft 身份验证根证书颁发机构，这在 Windows 10 版本 1809 及更高版本和 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

原因：Publisher中的 AppxManifest.xml 属性必须与签名证书的 主题名称完全匹配，包括以相同顺序的所有可分辨名称字段。

修复：

从证书获取确切的主体名称：

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

更新 AppxManifest.xml 以完全匹配：

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

重新打包MakeAppx.exe并重新签名。

小窍门

使用Azure工件签名（以前称为受信任的签名）时，您的清单中的发布者值必须与您已验证的标识相匹配，该标识位于Azure门户中您的证书配置文件的Subject name字段中。

应用安装程序和网页传输错误

.appinstaller 文件中的架构版本不匹配

症状：应用安装程序无法分析或处理 .appinstaller 文件，通常出现有关无效文件或不受支持的架构的一般错误。

应用到：Windows 10及更高版本（依赖于版本 - 请参阅表）

Cause：Uri 根元素的 <AppInstaller> 属性指定安装版本的Windows不支持的架构版本。

Windows版本的Schema版本：

Windows 版本	最低支持的架构版本
Windows 10版本 1709	1.0.0.0
Windows 10版本 1803	1.1.0.0
Windows 10版本 1809	1.2.0.0
Windows 10版本 1903 及更高版本，Windows 11	1.3.0.0, 1.4.0.0, 1.5.0.0

修复：将文件中的架构 URI .appinstaller 设置为最低支持 OS 所需的最低版本：

<?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版本，请避免使用最新的架构版本。

提供不正确的 MIME 类型或缺少 Content-Length 的文件

症状：从 HTTP/HTTPS 终结点安装应用安装程序失败。此错误可能是通用的，例如 0x80072F76 （“未知错误”）或“应用安装失败”。

应用到：Windows 10及更高版本

原因：Web 服务器正在为 .msix、.msixbundle 或 .appinstaller 文件提供服务，这些文件具有错误的 Content-Type 标头，或者省略了 Content-Length 标头。

修复：将 Web 服务器配置为使用正确的 MIME 类型为 MSIX 相关文件提供服务：

文件扩展名	必需的 MIME 类型
`.msix`	`application/msix`
`.msixbundle`	`application/msixbundle`
`.appinstaller`	`application/appinstaller`
`.appx`	`application/appx`
`.appxbundle`	`application/appxbundle`

此外，请确保每个响应都包含一个有效的 Content-Length 标头，这适用于这两个标头 GET 和 HEAD 请求。

对于 IIS，请在 web.config 中添加 MIME 类型映射。对于Azure Static Web Apps或GitHub页面，这些扩展的 MIME 类型可能需要显式配置或自定义托管解决方案。

缺少依赖项

未安装框架包（VCLibs、.NET、Windows 应用 SDK）

Symptom：应用成功安装，但在启动时崩溃，或者安装失败，并出现依赖项错误，引用包系列名称（如 Microsoft.VCLibs、Microsoft.WindowsAppRuntime 或 Microsoft.NET.Native）。

应用到：Windows 10及更高版本，Windows 11

常见框架及其获取位置：

Framework	何时需要	来源
VCLibs （x64/x86/arm64）	应用使用 C++ 运行时	Microsoft Store（自动安装）或 direct download
.NET 8 桌面运行时	应用的目标版本是.NET 8	包含在 Windows 应用 SDK 中，或直接下载
Windows 应用 SDK （WinAppsDK）	应用使用 WinUI 3 或其他 WinAppSDK API	GitHub 上的 Windows 应用 SDK 版本发布

针对开发修复：通过 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>

注释

通过 Microsoft Store 分发时，会自动下载并安装框架依赖项。仅旁加载和企业部署需要手动依赖项管理。

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 运行程序映像中。

修复：

Option 1 — 在管道中安装 Windows SDK （GitHub Actions）：

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

选项 2 - 使用 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 }}

Option 3 — 使用Azure工件签名（建议用于生产）：

- 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

注释

GitHub操作名为 azure/trusted-signing-action（前服务名称）。无论重新命名为Artifact签名，这仍然是官方行动。

要了解 CI/CD 签名设置过程的完整指南，请参阅对 MSIX 包进行签名 - 端到端指南。

运行时和虚拟化行为

MSIX 包在轻型应用容器中运行。某些看似 bug 的行为实际上是由设计引起的，容器会截获文件和注册表操作来保护系统的其余部分。

为何文件写入似乎会消失（VFS 文件重定向）

症状：应用将文件写入到运行时等 C:\Program Files\MyApp\config.ini 路径，但该文件不会出现在那里。应用正确读取该值，但其他进程或用户看不到该值。

应用到：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 的写入操作，并将其重定向至一个每个包独立的注册表配置单元，与系统的其他部分相隔离。卸载后，将删除 hive。

选项：

将每个用户的设置写入到HKEY_CURRENT_USER\Software\<AppName> — 这些设置不会虚拟化和持久化。
将 Windows ApplicationData API 用于结构化设置存储。
使用 <Extensions> / <com:Extension> 机制声明必须在 AppxManifest.xml 中跨用户或进程共享的注册表项。

若要更深入地了解 MSIX 容器行为，请参阅了解打包的桌面应用如何在 Windows 上运行。

Windows 10 MSIX 限制

某些 MSIX 功能需要Windows 11或特定的Windows 10版本。如果要部署到Windows 10设备，请注意以下事项。

Windows 10版本 2004（内部版本 19041）或更高版本所需的功能。

功能	最低版本
自动更新 2021 架构（`ShowPrompt`，`UpdateBlocksActivation`）	Windows 10 2004 （19041）
包完整性强制实施（`uap10:PackageIntegrity`）	Windows 10 2004 （19041）
应用安装器自动修复	Windows 10 2004 （19041）
没有用于安装受信任的应用包的单独旁加载政策开关；请参阅启用设备以进行开发以了解当前要求。	Windows 10 2004 （19041）

需要Windows 11的功能

功能	备注
不带完整打包的稀疏包标识	需要Windows 11
MSIX 支持具有外部位置的无封装应用（完整平台支持）	Windows 11中改进了一些 API
改进了每台计算机 MSIX 安装性能	Windows 11优化

版本低于 1709 的 Windows 10 设备

在 1709 之前的 Windows 10 版本中不支持 MSIX（Fall Creators Update）。若要将 MSIX 包部署到这些设备，请使用 MSIX Core，该层为下层Windows 10版本提供兼容性层。

清单插件

某些 AppxManifest.xml 命名空间扩展仅适用于 Windows 11。在面向 Windows 10 的软件包中声明它们可能会导致在打包过程中架构验证失败，或者在安装期间被拒绝。检查每个扩展列出的应用包清单架构参考MinOSVersion。

调试提示

若要验证特定Windows 10版本中有哪些 MSIX 功能可用，请检查 MSIX 功能和受支持的平台页，其中列出了 OS 版本提供的功能可用性。

反馈

此页面是否有帮助？

Last updated on 2026-04-15

MSIX 故障排除指南

安装错误

0x80070005 — 访问被拒绝

由于应用正在使用，包安装被阻止

MinVersion 或体系结构不匹配

Add-AppxPackage 成功，但“开始”菜单中缺少应用

签名和证书错误

证书不受信任（0x800B0109）

Publisher名称不匹配（0x8007000B，事件 ID 150）

应用安装程序和网页传输错误

.appinstaller 文件中的架构版本不匹配

提供不正确的 MIME 类型或缺少 Content-Length 的文件

缺少依赖项

未安装框架包（VCLibs、.NET、Windows 应用 SDK）

CI/CD 中找不到 SignTool

运行时和虚拟化行为

为何文件写入似乎会消失（VFS 文件重定向）

为什么注册表写入似乎消失 （注册表虚拟化）

Windows 10 MSIX 限制

Windows 10版本 2004（内部版本 19041）或更高版本所需的功能。

需要Windows 11的功能

版本低于 1709 的 Windows 10 设备

清单插件

调试提示

相关资源

反馈

其他资源

为什么注册表写入似乎消失（注册表虚拟化）