重要
Windows 应用程序开发 CLI 目前为 公开预览。 在最终发布之前，功能和命令可能会更改。
此页面记录 winapp CLI 的所有可用命令。
全局选项
所有命令都支持以下全局选项：
| 选项 | 说明 |
|---|---|
--verbose、-v |
启用详细日志记录输出 |
--quiet、-q |
禁止显示进度消息 |
--help、-h |
显示命令帮助 |
全局缓存目录
WinApp 创建一个目录来缓存可在多个项目之间共享的文件。 默认情况下，该属性为 $UserProfile/.winapp。
若要使用其他位置，请设置 WINAPP_CLI_CACHE_DIRECTORY 环境变量：
$env:WINAPP_CLI_CACHE_DIRECTORY = "d:\temp\.winapp"
安装程序命令
初始化
使用 Windows SDK、Windows App SDK 以及新式 Windows 开发所需的资源来初始化目录。
winapp init [base-directory] [options]
参数：
| 论点 | 说明 |
|---|---|
base-directory |
应用/工作区的基/根目录（默认值：当前目录） |
选项：
| 选项 | 说明 |
|---|---|
--config-dir <path> |
要读取/存储配置的目录（默认值：当前目录） |
--setup-sdks |
SDK 安装模式： stable （默认）、 preview、 experimental或 none |
--ignore-config、--no-config |
不要将配置文件用于版本管理 |
--no-gitignore |
不要更新 .gitignore 文件 |
--use-defaults、--no-prompt |
不提示，默认使用所有提示的默认值 |
--config-only |
仅处理配置文件操作，跳过包安装 |
功能：
-
winapp.yaml创建配置文件 - 下载 Windows SDK 和 Windows App SDK 包
- 生成 C++/WinRT 标头和二进制文件
- 创建 AppxManifest.xml
- 设置生成工具并启用开发人员模式
- 更新 .gitignore 以排除生成的文件
自动 .NET 项目检测：
在目标目录中找到 .csproj 文件时，init 使用简化的 .NET 特定流程：
- 验证并更新
TargetFramework为 Windows 兼容的 TFM（例如net10.0-windows10.0.26100.0） - 直接在
.csproj中将Microsoft.WindowsAppSDK和Microsoft.Windows.SDK.BuildTools添加为 NuGetPackageReference条目。 - 生成
appxmanifest.xml、资产和开发证书 -
不创建
winapp.yaml或下载 C++ 投射（请使用dotnet restore处理 NuGet 包）
示例：
# Initialize current directory
winapp init
# Initialize with experimental packages
winapp init --setup-sdks experimental
# Initialize specific directory without prompts
winapp init ./my-project --use-defaults
# Initialize a .NET project (auto-detected from .csproj)
cd my-dotnet-app
winapp init
小窍门
如果运行了init和--setup-sdks none后又需要SDK，请重新运行winapp init --use-defaults --setup-sdks stable。 这会保留现有文件（清单等）。
恢复
根据现有 winapp.yaml 配置还原包并重新生成文件。
winapp restore [options]
选项：
| 选项 | 说明 |
|---|---|
--config-dir <path> |
包含 winapp.yaml 的目录（默认值：当前目录） |
功能：
- 读取现有
winapp.yaml配置 - 将 SDK 包下载/更新到指定版本
- 重新生成 C++/WinRT 标头和二进制文件
注释
对于使用 winapp init 初始化的.NET项目，没有 winapp.yaml。 请使用 dotnet restore 来还原 NuGet 包。
示例：
# Restore from winapp.yaml in current directory
winapp restore
更新
将包更新到其最新版本并更新配置文件。
winapp update [options]
选项：
| 选项 | 说明 |
|---|---|
--config-dir <path> |
包含 winapp.yaml 的目录（默认值：当前目录） |
--setup-sdks |
SDK 安装模式： stable （默认）、 preview、 experimental或 none |
功能：
- 读取现有
winapp.yaml配置 - 将所有包更新到其最新可用版本
- 使用新的版本号更新
winapp.yaml文件 - 重新生成 C++/WinRT 标头和二进制文件
示例：
# Update packages to latest versions
winapp update
# Update including experimental packages
winapp update --setup-sdks experimental
打包命令
pack
从准备好的应用程序目录创建 MSIX 包。 要求 appxmanifest.xml 文件存在于目标目录、当前目录或通过 --manifest 选项传递。
winapp pack <input-folder> [options]
参数：
| 论点 | 说明 |
|---|---|
input-folder |
包含要打包的应用程序文件的目录 |
选项：
| 选项 | 说明 |
|---|---|
--output <filename> |
输出 MSIX 文件名（默认值： <name>.msix） |
--name <name> |
包名（默认值：从清单中获取） |
--manifest <path> |
AppxManifest.xml 的路径（默认值：自动检测） |
--cert <path> |
签名证书的路径（启用自动签名） |
--cert-password <password> |
证书密码（默认值：“password”） |
--generate-cert |
生成新的开发证书 |
--install-cert |
将证书安装到计算机 |
--publisher <name> |
证书生成发布者名称 |
--self-contained |
捆绑Windows App SDK运行时 |
--skip-pri |
跳过 PRI 文件生成 |
--executable <path> |
相对于输入文件夹的可执行文件的路径。 用于解析 $targetnametoken$ 清单文件中的占位符。 |
功能：
- 验证和处理 AppxManifest.xml 文件
- 解析清单文件中的
$placeholder$令牌（参见清单占位符） - 确保合理的框架依赖项
- 使用注册信息更新并行清单
- 处理 Windows App SDK 的独立部署
- 如果提供证书，请对包进行签名
示例：
# Package directory with auto-detected manifest
winapp pack ./dist
# Package with custom output name and certificate
winapp pack ./dist --output MyApp.msix --cert ./cert.pfx
# Package with generated and installed certificate and self-contained runtime
winapp pack ./dist --generate-cert --install-cert --self-contained
# Package with explicit executable
winapp pack ./dist --executable MyApp.exe
创建调试身份
使用 外部位置/稀疏打包创建用于调试的应用标识，而无需进行完整的 MSIX 打包。
winapp create-debug-identity [entrypoint] [options]
参数：
| 论点 | 说明 |
|---|---|
entrypoint |
可执行文件（.exe）或需要标识的脚本的路径 |
选项：
| 选项 | 说明 |
|---|---|
--manifest <path> |
AppxManifest.xml 的路径（默认值： ./appxmanifest.xml） |
--no-install |
创建后不要安装包 |
--keep-identity |
保留清单标识原样，而不附加 .debug 到包名称和应用程序 ID |
功能：
- 修改可执行文件的并行清单
- 为身份注册稀疏包
- 启用对需要身份验证的 API 进行调试
示例：
# Add identity to executable using local manifest
winapp create-debug-identity ./bin/MyApp.exe
# Add identity with custom manifest location
winapp create-debug-identity ./dist/app.exe --manifest ./custom-manifest.xml
清单命令
清单生成
从模板生成 AppxManifest.xml。
winapp manifest generate [directory] [options]
参数：
| 论点 | 说明 |
|---|---|
directory |
要在其中生成清单的目录（默认值：当前目录） |
选项：
| 选项 | 说明 |
|---|---|
--package-name <name> |
包名称（默认：文件夹名称） |
--publisher-name <name> |
Publisher CN（默认值：CN=<current user>） |
--version <version> |
版本（默认值：“1.0.0.0”） |
--description <text> |
说明（默认值：“我的应用程序”） |
--entrypoint <path> |
入口点的可执行文件或脚本 |
--template <type> |
模板类型： packaged （默认值） 或 sparse |
--logo-path <path> |
徽标图像文件的路径 |
--if-exists <Error\|Overwrite\|Skip> |
文件已存在时的行为（默认值：错误） |
模板：
-
packaged- 标准打包的应用清单 -
sparse- 使用稀疏/外部位置打包的应用程序清单
清单占位符
生成的清单使用 $placeholder$ 标记，这些标记在打包时由美元符号分隔并自动解析。
| 占位符 | 已解析为 | 示例 |
|---|---|---|
$targetnametoken$ |
不带扩展名的可执行文件名称 |
Executable="$targetnametoken$.exe" 变为 Executable="MyApp.exe" |
$targetentrypoint$ |
Windows.FullTrustApplication |
始终自动解决 |
如何解析占位符：
-
winapp pack$targetnametoken$通过使用--executable选项或自动检测输入文件夹中的单个.exe来解析。 - 当提供入口点参数时，
winapp create-debug-identity$targetnametoken$会进行解析。 -
winapp manifest generate --executable从可执行文件中提取元数据，但在清单中保留$targetnametoken$.exe以供以后解析。
小窍门
将 $targetnametoken$保留在已签入清单中可避免硬编码可执行文件名称，并且适用于 winapp pack 和 Visual Studio 构建。
示例：
# Generate standard manifest interactively
winapp manifest generate
# Generate with all options specified
winapp manifest generate ./src --package-name MyApp --publisher-name "CN=My Company" --if-exists overwrite
清单 更新资源
从单个源映像生成所有必需的 MSIX 映像资产。
winapp manifest update-assets <image-path> [options]
参数：
| 论点 | 说明 |
|---|---|
image-path |
源图像文件的路径（PNG、JPG、GIF 等） |
选项：
| 选项 | 说明 |
|---|---|
--manifest <path> |
AppxManifest.xml 文件的路径（默认值：搜索当前目录） |
获取单个源映像，并在正确的维度上自动生成所有 12 个必需的 MSIX 映像资产。 资产将被保存到相对于清单位置的Assets目录。
示例：
# Generate assets with auto-detected manifest
winapp manifest update-assets mylogo.png
# Specify manifest location explicitly
winapp manifest update-assets mylogo.png --manifest ./dist/appxmanifest.xml
证书和签名命令
证书生成
生成用于包签名的开发证书。
winapp cert generate [options]
选项：
| 选项 | 说明 |
|---|---|
--manifest <appxmanifest.xml> |
从 appxmanifest.xml中提取publisher信息 |
--publisher <name> |
证书发布者名称 |
--output <path> |
输出证书文件路径 |
--password <password> |
证书密码（默认值：“password”） |
--valid-days <days> |
证书有效天数（默认值：365） |
--install |
生成后将证书安装到本地计算机存储 |
--if-exists <Error\|Overwrite\|Skip> |
证书文件已存在时的行为（默认值：错误） |
证书安装
将证书安装到计算机证书存储。
winapp cert install <cert-path>
参数：
| 论点 | 说明 |
|---|---|
cert-path |
要安装的证书文件的路径 |
示例：
# Generate certificate for specific publisher
winapp cert generate --publisher "CN=My Company" --output ./mycert.pfx
# Install certificate to machine
winapp cert install ./mycert.pfx
标识
使用证书对 MSIX 包和可执行文件进行签名。
winapp sign <file-path> [options]
参数：
| 论点 | 说明 |
|---|---|
file-path |
要签名的 MSIX 包或可执行文件的路径 |
选项：
| 选项 | 说明 |
|---|---|
--cert <path> |
签名证书的路径 |
--cert-password <password> |
证书密码（默认值：“password”） |
示例：
# Sign MSIX package
winapp sign MyApp.msix --cert ./mycert.pfx
# Sign executable
winapp sign ./bin/MyApp.exe --cert ./mycert.pfx --cert-password mypassword
实用工具命令
工具
直接访问Windows SDK工具。 使用 Microsoft.Windows.SDK.BuildTools 中提供的工具。
winapp tool <tool-name> [tool-arguments]
可用工具：
-
makeappx- 创建和操作应用包 -
signtool- 对文件进行签名并验证签名 -
mt- 并行程序集的清单工具 - Microsoft.Windows.SDK.BuildTools 中的其他 Windows SDK 工具
示例：
# Use signtool to verify signature
winapp tool signtool verify /pa MyApp.msix
存储
运行 Microsoft Store 开发人员 CLI 命令。 此命令会下载Microsoft商店开发者 CLI（如果还未下载）。 在 Microsoft 应用商店开发人员 CLI 中了解详细信息。
winapp store [args...]
参数：
| 论点 | 说明 |
|---|---|
args... |
直接传递给 msstore CLI 的参数 |
示例：
# List all apps in your Microsoft Partner Center account
winapp store app list
# Publish a package to the Microsoft Store
winapp store publish ./myapp.msix --appId <your-app-id>
get-winapp-path
获取安装 Windows SDK 组件的路径。
winapp get-winapp-path [options]
返回 .winapp 工作区目录、包安装目录和生成的标头位置的路径。
Node.js/Electron 命令
这些命令仅在 NPM 包中可用。
node 创建插件
使用 Windows SDK 和 Windows App SDK 生成本机 C++ 或 C# 加载项模板。
npx winapp node create-addon [options]
选项：
| 选项 | 说明 |
|---|---|
--name <name> |
Addon 名称（默认: “nativeWindowsAddon”） |
--template |
选择加载项的类型： cs 或 cpp （默认值： cpp） |
--verbose |
启用详细输出 |
功能：
- 创建带有模板文件的插件目录
- 使用 Windows SDK 示例生成 binding.gyp 和插件文件
- 安装所需的 npm 依赖项
- 将生成脚本添加到 package.json
示例：
# Generate addon with default name
npx winapp node create-addon
# Generate custom named C# addon
npx winapp node create-addon --name myWindowsAddon --template cs
节点 添加 Electron 调试 身份
通过使用精简打包，将应用程序标识符添加到 Electron 开发流程中。 需要 appxmanifest.xml（可以使用winapp init或winapp manifest generate创建一个）。
重要
稀疏打包 Electron 应用程序存在一个已知问题，导致应用在启动时崩溃或不呈现 Web 内容。 此问题已在 Windows 中修复，但尚未传播到所有设备。 可以使用--no-sandbox标志作为变通方法，在Electron 应用中禁用沙盒。 此问题不会影响完整的 MSIX 打包。
若要撤消 Electron 调试标识，请使用 winapp node clear-electron-debug-identity。
npx winapp node add-electron-debug-identity [options]
选项：
| 选项 | 说明 |
|---|---|
--manifest <path> |
自定义 appxmanifest.xml 的路径（默认值：当前目录中的 appxmanifest.xml） |
--no-install |
不要安装或修改依赖项;仅配置 Electron 调试标识 |
--keep-identity |
保留清单标识不变，而不追加 .debug |
--verbose |
启用详细输出 |
示例：
# Add identity to Electron development process
npx winapp node add-electron-debug-identity
# Use a custom manifest file
npx winapp node add-electron-debug-identity --manifest ./custom/appxmanifest.xml
节点清除电子调试身份指令 (node clear-electron-debug-identity)
通过还原备份中的原始 electron.exe 文件，从 Electron 调试过程中删除包标识。
npx winapp node clear-electron-debug-identity [options]
选项：
| 选项 | 说明 |
|---|---|
--verbose |
启用详细输出 |
示例：
# Remove identity from Electron development process
npx winapp node clear-electron-debug-identity
