winui-dev-workflow

需要 WinApp CLI 0.7+。

创建或打开项目

新应用 — 让 WinApp CLI 安装/更新官方模板并生成项目：

winapp new --name <AppName> --template winui-mvvm --template-version latest --use-defaults
cd <AppName>

运行 winapp new --list，查看当前已安装模板的简称。不要单独安装模板包，也不要预先创建输出目录。

现有应用 — 阅读 .csproj，了解：

• <TargetFramework>（例如，net10.0-windows10.0.26100.0）
• <PackageReference> 版本（WindowsAppSDK、CommunityToolkit）
• 项目结构和既定模式

添加或检查每个应用的分析器

为每个应用项目添加最新的稳定版分析器；不要假定模板已包含它：

dotnet add .\MyApp.csproj package Microsoft.Windows.SDK.BuildTools.WinUIAnalyzer

在引用中保留 PrivateAssets="all"。它会在常规 CLI、IDE 和 CI 构建中加载；WinApp CLI 不会注入它。如果无法获取此包，请继续操作，并告知用户其潜在运行时问题检查未运行。仅撤销本次尝试添加的不完整引用；不要删除现有引用，也不要掩盖其他还原失败。

对于其他包，除非项目有版本策略或用户指定特定版本，否则优先使用最新稳定版。在编写 API 假设之前，使用 winapp find-api 并通过 --project-dir <app-project-dir>（或在解决方案中使用 --project <name>）限定到已还原的应用；参见 winui-design。

构建和运行（JIT 开发）

winapp run . --detach --json

如需进行 UI 测试，请参见 winui-ui-testing；它会自行选择执行目标。

常规 winapp run 使用构建/JIT 路径，即使使用 -c Release 也是如此；它不会验证 Native AOT。项目选择存在歧义时，请显式指定 .csproj；选项请参见 winapp run --help。

如果构建失败： 阅读所有错误，一次性批量修复，然后重新运行同一命令。

Native AOT 发布运行

若要部署到 AOT，请在应用项目中设置 <PublishAot>true</PublishAot>（这也会在开发期间启用分析）；若只进行一次试用，请传入 -p PublishAot=true。--aot 会执行发布而非构建；请选择可在此计算机上运行的 --arch：

winapp run . --aot -c Release --arch <x64|arm64> --detach --json
winapp run . --aot -c Release --arch <x64|arm64> -p PublishAot=true --detach --json

修复 IL/CsWinRT 警告，不要抑制它们。请参见 winui-packaging 的 references/sourcegen-patterns.md。

诊断崩溃

使用 --debug-output 附加运行，并通过 mode: "async" 调用它，然后读取同一 shell。在 WinUI 崩溃时，挂起异常排查会揭示隐藏在不透明 0x8000FFFF / E_FAIL 后面的真实 XAML 错误；添加 --symbols 可获取更丰富的本机堆栈帧。首次崩溃时会下载调试器组件；离线时，请将 WINAPP_DBGTOOLS_DIR 设为现有的 Debugging Tools for Windows 安装目录。--debug-output 不能与 --json 或 --no-launch 同时使用。

常见错误

错误	修复方法
未启用开发人员模式	设置 → 系统 → 面向开发人员 → 开启
缺少 CS0234/CS0246 类型	添加 using 或 dotnet add package
NETSDK1136 要求指定平台	指定 Windows TFM（例如 net10.0-windows10.0.26100.0）；如果项目已面向多个目标平台，请使用 -f <windows-tfm>
找不到 XLS0414 XAML 类型	添加 xmlns 声明
缺少 XDG0062 绑定路径	检查 ViewModel 中是否存在 x:Bind 属性
动态绑定值未更新	检查有效模式，包括继承的 x:DefaultBindMode；必要时使用 OneWay/TwoWay 并通知更改
应用静默退出	使用项目模式的 winapp run；不要绕过打包激活，直接运行 .exe
应用因不明确的 0x8000FFFF / E_FAIL 崩溃	请参阅 诊断崩溃
XAML 编译器静默崩溃	移除所有 PresentationCore.dll / System.Windows 引用
MSB3073 / XamlCompiler.exe ... exited with code 1，且未命名任何 .xaml 文件	旧版 WindowsAppSDK XAML 编译器错误——将 Microsoft.WindowsAppSDK NuGet 更新到最新版本（≥ 2.1.3，或 1.x 系列的 ≥ 1.8）
0x80073CF6 包安装失败	检查清单发布者和开发人员模式；通过 winapp new 创建的应用无需单独运行 winapp init
深层嵌套项目出现 0x80073CF9 /“Failed to reach state Staged”	对于打包应用，使用 --output-appx-directory "$env:LOCALAPPDATA\winapp-layout\<app>-<config>-<arch>" 重新运行，或将仓库移到更靠近驱动器根目录的位置。每种配置和体系结构都应使用唯一目录——已注册的开发包会持有该目录的实时引用，因此 Debug 和 Release 不得共用同一目录——重复使用前请清空目录，以免残留上次生成后新增的有效负载文件
0x8007000B 映像格式错误	平台目标不正确——请使用 x64 或 ARM64，而非 AnyCPU

先决条件

要求	此工作流所需条件
Windows	Windows 10 v1903+，并满足应用的 OS 要求
开发人员模式	开发部署时必须启用
.NET SDK	最低 8.0.100 ，并且还需安装应用 TFM 所要求的 SDK（例如，net10.0-windows… 需要 .NET 10）
WinApp CLI	0.7+
仅 Native AOT	MSVC C++ 构建工具（Visual Studio 或 Build Tools、使用 C++ 的桌面开发工作负载，以及目标体系结构工具）；常规构建不需要

如果缺少 WinApp CLI 或版本低于 0.7，请直接使用 winui-setup 安装或升级（无需管理员权限），并告知用户。安装任何需要管理员权限的组件前，请先征求同意——包括 .NET SDK、开发人员模式或 Native AOT 工具链；不要绕过这些要求。

重要规则

• 默认使用已打包模式，并使用项目模式的 winapp run 进行激活。
• 仅在明确要求进行非打包/调试实验时，才设置 WindowsPackageType=None；依赖包身份的 API 可能会失败，且仍需满足运行时要求。不得将此作为静默启动的变通方法。保留清单，并在实验后恢复原有的打包设置。
• 不要删除 Package.appxmanifest。
• ❌ 绝不要使用 AnyCPU——始终使用 x64 或 ARM64

参考

• winui-packaging — 直接从项目进行发布打包；无需开发注册。