winapp CLI

[!IMPORTANT] :warning: 状态：公开预览 — Windows 应用开发 CLI（winapp CLI）处于实验阶段并正在积极开发中。我们非常期待您的反馈！请通过创建 issue 分享您的想法。

[!NOTE] main 分支 包含正在 积极开发中 的工作。此处的文档、功能和行为可能与公开发布版本有所不同。有关最新稳定版本，请参阅 latest release。若要尝试最新的进行中构建，请参阅下方的 Install from latest build。

为什么？ • 快速入门 • 安装 • 使用 • 文档 • 反馈

Windows 应用开发 CLI (winapp CLI) 是一个用于管理 Windows SDK、打包、生成应用标识、清单、证书，以及在任何应用框架中使用构建工具的单一命令行界面。该工具弥合了跨平台开发与 Windows 原生功能之间的差距。

无论您使用 .NET/Win32、CMake、Electron 还是 Rust 进行开发，此 CLI 都能让您访问以下功能：

• 现代 Windows API - Windows App SDK 和 Windows SDK，支持自动设置和代码生成
• 包标识 - 无需完整打包即可快速添加包标识以进行调试和测试
• MSIX 打包 - 支持签名和商店就绪的应用打包
• 开发者工具 - 清单、证书、资源及构建集成

非常适合：

• 使用 Qt 或 Electron 等框架的跨平台开发者，希望获得原生 Windows 功能或针对 Windows 进行开发
• 喜爱当前工具的开发者，希望从 VS Code 或任何其他编辑器构建 Windows 应用
• 构建 CI/CD 流水线的开发者，以自动化 Windows 应用的构建

🤔 为什么？

许多 Windows API 要求你的应用具备包标识，从而让你能够利用 Windows 提供的一些操作系统组件，否则你将无法访问这些组件。借助标识，你的应用可以获得用户优先的功能，例如通知、操作系统集成以及设备端 AI。

我们的目标是支持身处任何位置的开发者，使用他们已经在使用的工具和框架。基于来自在 Windows 上发布跨平台应用的开发者的反馈，我们构建了此 CLI，以简化与 Windows 开发者平台的集成——通过几条命令即可处理 SDK 设置、头文件生成、清单、证书和打包：

没有 winapp CLI，设置项目需要 12 个手动步骤——下载 SDK、生成头文件、创建清单等。使用 CLI，只需 4 条命令。

包标识和 MSIX 打包所解锁的一些示例：

• 交互式原生通知 和通知管理
• 与 Windows 资源管理器、任务栏、共享面板 及其他 shell 界面的集成
• 协议处理器 (yourapp:// URIs)
• Web 到应用的链接 (yoursite.com 打开你的应用)
• 设备端 AI (本地 LLM、文本和图像 AI API)
• 通过 AppExecutionAlias 自定义 CLI 命令
• 受控访问摄像头、麦克风、位置 及其他设备（需用户同意）
• 后台任务 (应用关闭时运行)
• 文件类型关联 (使用你的应用打开 .xyz 文件)
• 启动任务 (在 Windows 登录时启动)
• 应用服务 (向其他应用暴露 API)
• 干净的安装/卸载 & 自动更新

✏️ 入门指南

查看我们的入门指南，了解如何设置环境、生成清单、资产和证书的分步说明，如何调试需要包标识的 API，以及如何将你的应用打包为 MSIX。

其他指南：

• 打包 EXE/CLI：将现有 exe/cli 打包为 MSIX 的分步指南
• MAUI (Windows)：使用生成的 resizetizer 清单打包并签名 .NET MAUI Windows 输出
• Electron JS/TypeScript 绑定 (仅限 npm)：通过 winapp init --add-js-bindings 选择启用自动生成的 WinRT 绑定。参见任务导向指南：
  • 文件选择器 — 从渲染进程打开原生 Windows 文件/文件夹选择器
  • Toast 通知 — 显示带有操作的 Windows Toast
  • Phi Silica (设备端 LLM) — 通过 Windows AI 进行本地文本生成
  • WinML 推理 — 使用 Windows ML 运行时运行 ONNX 模型

📦 安装

WinGet

使用 CLI 最简单的方式是通过 WinGet (Windows 包管理器)。在终端中，只需运行：

winget install Microsoft.winappcli --source winget

或者，如果您更喜欢使用 PowerShell 终端，您可以使用 WinGet PowerShell cmdlet（来自 Microsoft.WinGet.Client 模块）：

Install-WinGetPackage Microsoft.winappcli

NPM

你可以通过 NPM 为 Electron 项目安装 CLI：

npm install @microsoft/winappcli --save-dev

GitHub Actions / Azure DevOps

对于 GitHub Actions 或 Azure DevOps 上的 CI/CD 流水线，请使用 setup-WinAppCli action 在您的 runners/agents 上自动安装 CLI。

手动下载 Release

从 GitHub Releases 下载最新构建

从最新构建（main 分支）安装

[!CAUTION] 这些构建来自 main 分支，可能包含未发布的功能、破坏性更改或实验性功能。使用风险自负。

直接下载最新的 CI 构建产物（无需 GitHub 登录）：

Artifact	Description
CLI Binaries	原生 CLI 可执行文件 (win-x64, win-arm64)
npm Package	@microsoft/winappcli .tgz 包
MSIX Packages	MSIX 安装程序包（自签名）
NuGet Packages	NuGet .nupkg 包

下载链接无法使用？

上述直接链接由 nightly.link 提供，这是一个第三方服务。如果它们停止工作，您可以直接从 GitHub Actions 下载相同的产物：

1. 前往 Build and Package workflow runs（筛选为 main 上的成功构建）
2. 点击最近的工作流运行
3. 向下滚动到 Artifacts 部分并下载您需要的内容

注意：从 GitHub Actions 下载产物需要您登录 GitHub。

📋 用法

安装完成后（参见上方 Installation），通过调用 CLI 来验证安装：

winapp --help

或如果使用 Electron/Node.js

npx winapp --help

命令概览

设置命令：

• init - 使用 Windows SDK 和 App SDK 初始化项目
• restore - 还原包和依赖项
• update - 将包和依赖项更新到最新版本

应用标识与调试：

• pack - 从目录创建 MSIX 包
• run - 作为打包应用程序运行应用以进行调试（松散布局注册）
• create-debug-identity - 为现有 exe 添加稀疏包标识
• embed-identity - 通过嵌入 <msix> 元素将 exe 连接到其稀疏标识包
• unregister - 移除由 run 或 create-debug-identity 注册的侧载开发包
• manifest - 生成和管理 AppxManifest.xml 文件

另请参阅：调试指南 — 在 winapp run 和 create-debug-identity 之间进行选择、IDE 设置以及调试场景。

证书与签名：

• cert - 生成并安装开发证书
• sign - 对 MSIX 包和可执行文件进行签名
• az-sign - 使用 Azure Trusted Signing 进行签名（云托管标识，无需本地 PFX）
• create-external-catalog - 为 TrustedLaunch 稀疏包生成 CodeIntegrityExternal.cat

开发工具：

• tool - 访问 Windows SDK 工具
• store - 运行 Microsoft Store Developer CLI 命令
• get-winapp-path - 获取已安装 SDK 组件的路径

发现：

• find-ui - 搜索 WinUI 控件和示例（WinUI 3 Gallery + Windows Community Toolkit；Reactor 通过 --source reactor 可选启用）以获取可用的代码示例

Node.js/Electron 特定：

• node create-addon - 生成原生 C# 或 C++ 插件
• node add-electron-debug-identity - 为 Electron 进程添加身份
• node clear-electron-debug-identity - 从 Electron 进程中移除身份

完整的 CLI 用法可在此处找到：Documentation 完整的 NPM 用法可在此处找到：NPM Programmatic API Reference

🧾 示例

本仓库包含演示如何使用 CLI 配合各种框架的示例：

示例	描述
C++ App	使用 CMake 的原生 C++ Win32 应用程序
.NET Console	.NET 控制台应用程序
WPF App	WPF 桌面应用程序
WinUI App	通过 winapp run <csproj> 注册并启动的打包 WinUI 3 应用
WinUI Unpackaged App	通过 winapp run <csproj> 启动的非打包 WinUI 3 应用
WinUI Solution	多项目 .sln（应用 + 测试项目），演示 winapp run 解决方案模式的自动选择
Electron	包含 appxmanifest、资源、原生 C++ 插件和 C# 插件的 Electron Forge 应用
Electron WinML	使用 Windows ML 进行图像分类的 Electron 应用
Node.js WinUI 3	直接从 JavaScript 创建的原生 WinUI 3 控件
Rust App	使用 Windows API 的 Rust 应用程序
Tauri App	具有 Rust 后端的 Tauri 跨平台应用
Flutter App	具有包身份和 Windows App SDK 的 Flutter 桌面应用
Sparse App	具有生产级稀疏打包（仅身份 MSIX）和 Inno Setup 安装程序的 WPF 应用

🧩 VS Code 扩展

WinApp VS Code 扩展 将 WinApp CLI 引入 Visual Studio Code。它可以在不离开编辑器的情况下初始化项目、使用包标识进行调试、打包、签名等。按 F5 即可使用标识启动你的应用并自动附加调试器。

从 Visual Studio Marketplace 安装。在 microsoft/WinAppVSCE 查看 WinApp VS Code 扩展的仓库。

🤖 与 AI 编码代理配合使用

winapp 提供了一个单一插件（位于 plugins/winapp/）——包含一个代理和技能——通过各自的插件市场分发给 GitHub Copilot 和 Claude Code。

GitHub Copilot CLI（全局——适用于所有项目）

copilot plugin install microsoft/WinAppCli

Claude Code

claude plugin marketplace add microsoft/WinAppCli
claude plugin install winappcli@winappcli

这使代理能够全面理解 winapp 命令、工作流程和故障排除。

🔧 反馈与支持

提交问题、功能请求或错误报告：请确保你提交的问题不是重复的

需要帮助或对 Windows 应用开发 CLI 有疑问？请访问我们的 支持指南 了解有关问题模板和分诊流程的信息。

贡献

本项目欢迎贡献和建议。 大多数贡献需要你同意贡献者许可协议（CLA），声明你有权并且确实授予我们使用你贡献的权利。有关详细信息，请访问 贡献者许可协议。

当你提交一个 pull request 时，CLA bot 会自动判断你是否需要提供 CLA，并相应地标记该 PR（例如，状态检查、评论）。只需按照 bot 提供的说明操作即可。你只需在所有使用我们 CLA 的仓库中执行一次此操作。

本项目已采纳 Microsoft Open Source Code of Conduct。 如需更多信息，请参阅 Code of Conduct FAQ 或联系 opencode@microsoft.com 提出任何额外的问题或意见。

要构建 CLI：

# Build the CLI and package for npm, NuGet, and MSIX from the repo root
.\scripts\build-cli.ps1

二进制文件和软件包将放置在 artifacts 文件夹中

在推送前审查你的更改

面向开发者的 AI 技能位于 .github/skills/。 在推送 PR 之前，你可以要求 Copilot CLI（或任何读取技能文件的 agent）“审查我的 PR”——pr-review 技能会并行分发子 agent，涵盖安全性、正确性和测试、 CLI 用户体验、替代方案、必要性与简洁性、发布表面 （文档/示例/打包），以及不同模型的交叉检查。然后它会构建并 运行 CLI 以验证关键发现，并在 stdout 上打印一个简短的列表。

商标

本项目可能包含项目、产品或服务的商标或徽标。对 Microsoft 商标或徽标的授权使用须遵守并遵循 Microsoft 的商标和品牌指南。 在本项目的修改版本中使用 Microsoft 商标或徽标不得引起混淆或暗示 Microsoft 的赞助。 任何对第三方商标或徽标的使用均受该第三方政策约束。