WinAppCLI：快速 Windows 应用开发的命令行工具
WinAppCLI：快速 Windows 应用开发的命令行工具
从终端一次性构建、打包并部署 Windows 应用，使用统一、简洁的命令行界面。
为什么选择 WinAppCLI？
现代跨平台框架（Electron、.NET、C++、Rust、Tauri…）都能提供极佳的用户体验，但在 Windows 上部署仍显得与众不同，流程繁琐且易出错。你需要完成：
- 安装并管理完整的 Windows 及 Windows App SDK 工具集。
- 生成 AppxManifest.xml 文件，编码应用身份、功能权限与快捷方式信息。
- 创建并维护开发证书。
- 将应用打包为 MSIX 或 EXE。
- 对二进制文件进行签名，设置版本号，并配置面向商店的元数据。
逐一手工完成这些步骤既乏味又容易出错。WinAppCLI 将这些任务整合到一个体积小、维护良好的开源项目中。
- 一个工具，多框架支持 – Electron、.NET、C++、Rust、Tauri。
- 零摩擦 SDK 安装 – 自动获取最新版 Windows SDK 与 App SDK。
- 即时应用身份 – 仅调试时添加临时身份，无需完整打包。
- 快速且可复现的 MSIX 生成 – 适配 CI/CD 流水线。
- 开源 – MIT 许可证，完全可审计。
快速开始
1. 安装 WinAppCLI
| 平台 | 命令 |
|---|---|
| Windows（通过 WinGet） | winget install Microsoft.winappcli --source winget |
| Node / Electron | npm install @microsoft/winappcli --save-dev |
| CI 环境 | 使用 GitHub Actions 的 setup‑WinAppCli 操作，或在 runner 上通过 winget 安装 |
本地开发时，你也可直接从 GitHub releases 页面 下载最新发行版。
2. 验证安装
winapp --help
你应该能看到帮助菜单，包括 init、package、cert、manifest 等命令。
3. 初始化项目
# 在新建或现有的 Electron 项目中
winapp init
此命令会拉取所需 SDK，创建证书占位符，并生成 winapp.example.yaml（你可将其改名为 winapp.yaml）。
核心命令概览
| 命令 | 用途 |
|---|---|
init |
初始化 SDK 并生成 manifest 与身份架构 |
restore |
恢复 SDK 包与依赖 |
update |
更新 SDK 至最新版 |
package |
从源目录构建 MSIX 或 EXE 包 |
create-debug-identity |
为调试添加临时应用身份 |
manifest |
生成或更新 AppxManifest.xml |
cert |
创建或更新开发证书 |
sign |
用指定证书签名 MSIX 或 EXE |
tool |
暴露 Windows SDK 命令行工具 |
node create-addon |
为 Electron 生成 C# 或 C++ 插件 |
node add-electron-debug-identity |
为 Electron 进程添加调试身份 |
完整参考可在 官方文档 中查看。
示例项目
仓库包含一组即装即跑的示例，展示多栈实际使用场景。每个示例都包含 winapp.yaml 与简短 README。
- Electron – 使用 Electron Forge、原生 C++ 插件与 C# 模块。
- Electron WinML – 展示使用 Windows ML 的图像分类。
- C++ (Win32) – 纯 C++ 应用，使用 CMake 构建。
- .NET Console – .NET WinAppSDK 包装示例。
- WPF – 经典 Windows Presentation Foundation UI。
- Rust – 通过 windows-rs crate 调用本机 API。
- Tauri – Rust 后端支持跨平台前端。
运行示例只需三步：
cd samples/electron
npm install
npx winapp init
npx winapp package
生成的 dist 目录包含可 sideload 或上传商店的 MSIX 应用。
CI/CD 集成
WinAppCLI 旨在无缝融入现代流水线。
GitHub Actions
- name: Setup WinAppCLI
uses: microsoft/setup-winappcli@v1
- name: Build and Sign
run: |
winapp init
winapp package
winapp sign --certificate myCert.pfx --password ${{ secrets.CERT_PASSWORD }}
Azure DevOps
在流水线中加入官方 setup-WinAppCli 任务，或通过 winget 在代理上安装。
CLI 会暴露环境变量（例如 WINAPP_SDK_PATH），便于在其他工具中引用已安装 SDK。
常见问题与排查
| 症状 | 可能原因 | 解决方案 |
|---|---|---|
winapp: unrecognized command |
CLI 未在 PATH | 验证安装，重跑 winget install 或 npm，并将本地 node_modules/.bin 添加至 PATH |
| 签名失败并提示 The certificate was not found | 证书路径或密码错误 | 使用 --certificate 指定完整路径，或通过 --password / 环境变量 WINAPP_CERT_PASSWORD 传递密码 |
| Electron 与 .NET 构建之间身份冲突 | winapp.yaml 中存在重复身份 |
删除或重命名冲突的身份条目 |
| MSIX 安装失败，提示 signature is missing | 证书未受信任 | 在测试机上将开发证书安装至 受信任的根证书颁发机构 |
| --- |
贡献
WinAppCLI 是一个 MIT 许可证下的开源项目。欢迎你：
- 提出问题 – 缺陷报告、功能建议或使用疑问。
- 提交拉取请求 – 修复、改进或新增语言绑定。
- 贡献示例 – 为其他框架或构建系统添加支持。
所有贡献者须签署 Microsoft 的 Contributor License Agreement。详情请参阅 CONTRIBUTING.md。
最后想法
WinAppCLI 将 Windows 应用打包这项艰巨任务转化为可重复、可脚本化的过程。无论你是想为 Electron 项目添加原生 Windows 功能、为 .NET 开发者提供快速 MSIX 打包，还是 CI 工程师需要可靠构建步骤，这个 CLI 都是你工具链中强有力的补充。
快来试一试：通过 WinGet 或 NPM 安装，跑一个示例，告诉我们你的体验。凭借社区贡献与 Microsoft 牵线的路线图，WinAppCLI 正在成为跨平台时代 Windows 应用开发的事实标准。