将 CLI 可执行文件打包为 MSIX

本指南将指导你将现有的命令行可执行文件打包为 MSIX 包，以便通过 Windows 程序包管理器（winget）、Microsoft 应用商店或直接分发进行分发。

先决条件

  • 要打包的现有 CLI 可执行文件 （.exe）
  • Windows 10版本 1809 或更高版本

步骤

1. 组织您的命令行界面应用程序

将 CLI 可执行文件和任何依赖项放在专用文件夹中。 此文件夹将包含应在 MSIX 包中包含的所有文件。

mkdir MyCliPackage
cd MyCliPackage
# Copy your CLI executable and dependencies here

2.安装 winapp CLI

通过Windows 程序包管理器安装 winapp CLI，或者更新到最新版本（如果已安装）：

# Install (or update if already installed)
winget install microsoft.winappcli --source winget

3. 生成 Package.appxmanifest 文件

为 CLI 可执行文件生成基本 Package.appxmanifest 和所需资产：

winapp manifest generate --executable .\yourcli.exe

此命令在当前目录中创建一个 Package.appxmanifest 文件，其中包含从可执行文件填充的默认值。

4. 配置清单

编辑生成的 Package.appxmanifest 以自定义您的包。 下面的每个子步骤都说明了要更改的内容和原因。

4.1 添加所需的命名空间

如果元素尚不存在，请将 uap5 命名空间添加到 Package 元素。 在步骤 4.3 中，执行别名需要这一操作：

<Package
  xmlns="http://schemas.microsoft.com/appx/manifest/foundation/windows10"
  ...
  xmlns:uap="http://schemas.microsoft.com/appx/manifest/uap/windows10"
  xmlns:uap5="http://schemas.microsoft.com/appx/manifest/uap/windows10/5"
  xmlns:rescap="http://schemas.microsoft.com/appx/manifest/foundation/windows10/restrictedcapabilities"
  IgnorableNamespaces="uap uap5 rescap">

4.2 配置 Application 元素

在元素中 <uap:VisualElements> ，添加 AppListEntry="none" 以隐藏“开始”菜单中的应用。 CLI 工具从终端调用，因此不需要“开始”菜单条目：

<uap:VisualElements
    DisplayName="YourApp"
    Description="My Application"
    BackgroundColor="transparent"
    Square150x150Logo="Assets\Square150x150Logo.png"
    Square44x44Logo="Assets\Square44x44Logo.png"
    AppListEntry="none">
</uap:VisualElements>

4.3 添加执行别名扩展

添加执行别名，以便用户可以从任何终端窗口按名称运行 CLI。 在 <Application> 元素中添加此项（之后 <uap:VisualElements>）：

<Extensions>
  <uap5:Extension Category="windows.appExecutionAlias">
    <uap5:AppExecutionAlias>
      <uap5:ExecutionAlias Alias="yourcli.exe" />
    </uap5:AppExecutionAlias>
  </uap5:Extension>
</Extensions>

将 yourcli.exe 替换为您 CLI 所需的命令名称。 用户安装 MSIX 后，他们将能够使用此命令调用 CLI。

4.4 更新应用程序元数据

更新以下字段以匹配 CLI 应用程序。

重要

清单中的 Publisher 值必须与签名证书中的发布者匹配。 如果稍后生成证书（步骤 5），它将使用清单中的发布者。 如果在生成证书后更改发布者，则需要重新生成证书才能匹配。

  • Identity：更新 Name、Publisher 和 Version

    <Identity
  Name="YourCompany.YourCLI"
  Publisher="CN=Your Company"
  Version="1.0.0.0" />

  • 属性：更新显示名称、发布者显示名称和说明

    <Properties>
  <DisplayName>Your CLI Tool</DisplayName>
  <PublisherDisplayName>Your Company</PublisherDisplayName>
  <Description>Description of your CLI tool</Description>
  <Logo>Assets\StoreLogo.png</Logo>
</Properties>

  • VisualElements：更新显示名称和资源引用

    <uap:VisualElements
  DisplayName="Your CLI Tool"
  Description="Description of your CLI tool"
  BackgroundColor="transparent"
  Square150x150Logo="Assets\Square150x150Logo.png"
  Square44x44Logo="Assets\Square44x44Logo.png">
  <uap:DefaultTile Wide310x150Logo="Assets\Wide310x150Logo.png" />
  <uap:SplashScreen Image="Assets\SplashScreen.png" />
</uap:VisualElements>

注意：还应将适当的图标资产添加到包目录中的文件夹 Assets 。 虽然应用不会显示在“开始”菜单中，但应用商店提交仍需要图标，并可能出现在其他上下文中。

5. （可选） 生成开发证书

对于Microsoft Store外部的本地测试和分发，需要使用证书对 MSIX 包进行签名。

生成开发证书。 将其保留在 CLI 文件夹之外，以避免意外将其包含在包中：

# Navigate to a location outside your CLI folder (e.g., your home directory)
cd ~
winapp cert generate

这会在主目录中创建一个 devcert.pfx 文件（例如， C:\Users\yourname\devcert.pfx）。

若要信任开发计算机上的此证书，请安装它（需要管理员权限）：

# Run PowerShell as Administrator
winapp cert install ~\devcert.pfx

6. 打包您的CLI

现在，你已准备好创建 MSIX 包：

# Navigate back outside of your project folder
# Package with dev certificate (for local testing/distribution)
winapp pack .\path\to\MyCliPackage --cert .\path\to\devcert.pfx

这会在当前目录中创建一个 .msix 文件。

7.安装和验证

安装 MSIX 包以验证一切是否正常工作：

Add-AppxPackage .\MyCliPackage.msix

如果在步骤 4.3 中添加了执行别名，现在可以从任何终端运行 CLI：

yourcli --help

若要稍后卸载：

Get-AppxPackage *YourCLI* | Remove-AppxPackage

提示

  1. 准备好分发后，可以使用证书颁发机构的代码签名证书对 MSIX 进行签名，以便用户无需安装自签名证书
  2. Microsoft Store将为你签名 MSIX，无需在提交之前进行签名。
  3. 可能需要创建多个 MSIX 包，一个用于支持的每个体系结构（x64，Arm64）

后续步骤

  • 通过 winget 分发：将 MSIX 提交到 Windows 程序包管理器 社区存储库
  • 发布到 Microsoft Store：使用 winapp store 提交包
  • 设置 CI/CD：使用 GitHub Action 在流水线中自动打包
  • Last updated on