排查使用应用安装程序文件遇到的安装问题Troubleshoot installation issues with the App Installer file

如果在通过应用安装程序文件安装应用程序时发现任何问题,本主题将提供一些可能有帮助的故障排除指南。If you find any issues when installing an application from the App Installer file, this topic will provide some troubleshooting guidance that may help.

先决条件Prerequisites

为了能在 Windows 10 中旁加载应用,用户设备必须满足下面的要求:To be able to sideload apps in Windows 10, the user device must satisfy the next requirements:

  • 设备必须启用开发人员模式或旁加载应用。The device must be enabled for Developer Mode or Sideloading apps. 有关详细信息,请参阅启用设备进行开发See Enable your device for development to learn more.
  • 用于对程序包签名的证书必须受设备信任。The certificate used to sign the package must be trusted by the device. 有关更多详细信息,请参阅下面的受信任的证书部分。See the Trusted certificates section below for more details.
  • Windows 10 版本必须支持 .appinstaller 文件方案和分发协议。The Windows 10 version must support the .appinstaller file schema and the distribution protocol.

常见问题Common issues

在用户计算机中第一次旁加载应用程序时会遇到一些常见问题。There are some common issues when sideloading an application for first time in the user machine. 接下来的几个部分介绍了最常见的问题及其解决方案。The next few sections describe the most frequent issues and their solutions.

Windows 版本Windows version

每个 Windows 10 版本都改进了旁加载体验,在下表中可以找到每个主要版本中提供哪些功能。Each Windows 10 release improves on the sideloading experience, in the table below you will find which features are available in each major release. 如果你尝试使用你的 Windows 10 版本不支持的方法旁加载应用,将出现部署错误。If you try to sideload an app using a method not supported in your version of Windows 10, you will get a deployment error.

版本Version 旁加载注意事项Sideload Notes
版本 17134 (2018 更新,版本 1803) Build 17134 (April 2018 Update, version 1803) 通过 UNC/共享文件夹可以访问 .appinstaller 文件。The .appinstaller file can be accessed over UNC/Share folders. 还提供可配置的更新检查。Configurable update checks are also available.
内部版本 16299(Fall Creators Update 版本 1709)Build 16299 (Fall Creators Update, version 1709) 引入 .appinstaller 文件以便为你的应用提供自动更新。Introduced the .appinstaller file to provide automatic updates to your app. 此版本仅支持 HTTP 终结点。This version only supports HTTP endpoints. 更新检查不可配置,每 24 小时进行一次。Update checks are not configurable and happens each 24 hours.
内部版本 15063(Creators Update 版本 1703)Build 15063 (Creators Update, version 1703) 应用安装程序应用能够从 Microsoft Store 下载应用依赖项(仅在发布模式下)。The App Installer app is able to download app dependencies (only in release mode) from the Store.
内部版本 14393(周年更新版本 1607)Build 14393 (Anniversary Update, version 1607) 引入应用安装程序应用来安装 .appx 和 .appxbundle 文件,.appinstaller 文件不受支持。Introduced the App Installer app to install .appx and .appxbundle files, .appinstaller file is not supported.
内部版本 10586(11 月更新版本 1511)Build 10586 (November Update, version 1511) 只有通过 PowerShell 使用 Add-AppxPackage 命令才能使用旁加载。Sideload is only available through PowerShell using the Add-AppxPackage command.
内部版本 10240(Windows 10 版本 1507)Build 10240 (Windows 10, version 1507) 只有通过 PowerShell 使用 Add-AppxPackage 命令才能使用旁加载。Sideload is only available through PowerShell using the Add-AppxPackage command.

受信任的证书Trusted certificates

应用包必须使用设备信任的证书进行签名。App packages must be signed with a certificate that is trusted by the device. 默认情况下,在 Windows 操作系统中信任公共证书颁发机构提供的证书。Certificates provided by common Certificate Authorities are trusted by default in the Windows operating system.

但是,如果用于对应用程序包进行签名的证书不受信任,或者是在开发过程中使用的本地生成的/自签名证书,则应用安装程序可能会报告包不受信任,并会阻止其安装:However, if the certificate used to sign an app package is not trusted, or is a locally-generated/self-signed certificate used during development, the app installer may report that the package is untrusted and will prevent it from being installed:

.MSIX 签名,缺少或不受信任的证书

若要解决此问题,具有设备的本地管理员权限的用户必须使用 计算机证书 工具将证书导入以下容器之一:To solve this issue, a user with local administrator rights to the device must use the Computer Certificates tool to import the certificate into one of the following containers:

  1. 本地计算机:受信任人员Local Computer: Trusted People
  2. 本地计算机:不建议使用受信任的根颁发机构 () Local Computer: Trusted Root Authorities (not recommended)

重要

不要将包签名证书导入到用户证书存储中Do not import package signing certificates into the User Certificate store. 验证包标识时,应用安装程序不会搜索用户证书。The App Installer does not search User Certificates when verifying package identity.

从 "开始" 菜单中搜索,可以轻松找到计算机证书管理工具:The Computer Certificates management tool can be easily found by searching from the Start Menu:

通过 "开始" 菜单查找 "本地计算机证书" 工具

成功导入签名证书后,重新运行应用程序安装程序会显示包受信任并可以安装:Once the signing certificate is successfully imported, re-running the app installer will show that the package is trusted and can be installed:

使用受信任证书签名的 .MSIX

未安装依赖项Dependencies not installed

Windows 10 应用程序可以具有基于用于生成应用程序的应用程序平台的框架依赖项。Windows 10 applications can have framework dependencies based on the application platform used to generate the app. 如果你使用的是 C# 或 VB,应用将需要 .NET 运行时和 .NET 框架包。If you are using C# or VB, the app will require the .NET Runtime and .NET framework packages. C++ 应用程序需要 VCLibs。C++ applications require the VCLibs.

重要

如果应用包在发布模式配置中生成,将从 Microsoft Store 获取框架依赖项。If the app package is built in Release mode configuration, the framework dependencies will be obtained from the Microsoft Store. 但是,如果应用是在调试模式配置中生成的,将从 .appinstaller 文件中指定的位置获取依赖项。However, if the app is built in Debug mode configuration, the dependencies will be obtained from the location specified in the .appinstaller file.

无法访问文件Files not accessible

在从 HTTP 终结点安装时,务必验证是否可以访问具有正确 MIME 类型的所有文件。When installing from an HTTP endpoint, it is important to verify that all files are accessible with the correct MIME type. 验证这些文件的最简单方法是遵循 Visual Studio 所生成 HTML 页面中提供的链接。The easiest method to verify these files is by following the links provided in the HTML page generated by Visual Studio. 你必须检查这些文件:You must check these files:

  • .appinstaller 文件,可用作 application/xml.appinstaller file, available as an application/xml
  • .appx.appxbundle 文件,可用作 application/vns.ms-appx.appx and .appxbundle files, available as application/vns.ms-appx

隔离应用安装程序应用问题Isolate App Installer app issues

如果应用安装程序无法安装该应用程序,这些步骤将帮助你确定安装问题。If the App Installer cannot install the app, these steps will help identify the installation issue.

验证应用包文件安装Verify app package file installation

  • 将应用程序包文件下载到本地文件夹,然后使用 Add-appxpackage PowerShell 命令尝试安装该文件。Download the app package file to a local folder and try to install it using the Add-AppxPackage PowerShell command.

  • .appinstaller 文件下载到本地文件夹,并尝试使用 Add-AppxPackage -Appinstaller PowerShell 命令进行安装。Download the .appinstaller file to a local folder and try to install it using the Add-AppxPackage -Appinstaller PowerShell command.

应用安装程序事件日志App Installer event logs

应用部署基础结构将发出一些日志,这些日志通常适用于通过 Windows 事件查看器调试安装问题: Application and Services Logs -> Microsoft -> Windows -> AppxDeployment-ServerThe app deployment infrastructure emits logs that are often useful for debugging installation issues via the Windows Event Viewer: Application and Services Logs -> Microsoft -> Windows -> AppxDeployment-Server