WinUI 3项目必须用 Visual Studio 2022 创建
Visual Studio 2019 不支持 WinUI 3 桌面模板（
WinUI 3 in Desktop），哪怕装了最新 SDK 也会缺模板。VS 2022 17.0+ 是硬性门槛，且需启用
Universal Windows Platform development和
Desktop development with C++两个工作负载——后者常被忽略，但 WinUI 3 桌面应用依赖 C++/WinRT 运行时，没它会编译失败或
WindowsAppSDK初始化报错。
创建时选模板要认准：
Blank App, Packaged (WinUI 3 in Desktop)。别选
Blank App (WinUI 3 in UWP)，那是沙盒环境，不能访问文件系统、注册表或调用大多数桌面 API。
项目结构里关键的三个文件夹和一个 NuGet 包
新建后你会看到
App.xaml、
MainWindow.xaml、
Package.appxmanifest和
Microsoft.WindowsAppSDKNuGet 引用。前两者是 UI 入口，后者是运行时核心——版本必须与项目目标匹配：
Microsoft.WindowsAppSDK版本不能手动降级，否则
Windows.System.Launcher等 API 会提示“找不到类型”
Package.appxmanifest里的
TargetDeviceFamily Name="Desktop"必须存在，删掉会导致打包失败或安装后闪退
winui3\Microsoft.UI.Xaml的资源字典默认在
App.xaml中合并，若手动删了
MergedDictionaries，控件样式会回退成 Win32 默认灰框
调试阶段常见启动失败原因
按 F5 启动黑屏或直接退出，多数不是代码问题，而是环境或配置卡点：
Windows 版本低于 18362（1903）会报错0x80073D54，因为 WinUI 3 依赖 OS 层的
AppModel改进 没安装
Windows App SDK Runtime（非 SDK），即使开发机有 VS 也不代表已部署运行时；需单独下载
Microsoft.WindowsAppRuntime.1.5.x-x64.appinstaller安装
MainWindow.xaml.cs中误调用
Window.Activate()在
OnLaunched外触发，会导致窗口未初始化就激活，抛出
System.Runtime.InteropServices.COMException: 0x802A0001
首次写逻辑时绕不开的线程和生命周期
WinUI 3 的 UI 线程模型和 WPF/WinForms 不同：所有 UI 操作必须在主线程（DispatcherQueue），但
DispatcherQueue.TryEnqueue不再是唯一方式，推荐用
DispatcherQueue.GetForCurrentThread()获取实例后调用
EnqueueAsync：
await DispatcherQueue.GetForCurrentThread().EnqueueAsync(() =>
{
myButton.Content = "Done";
});
另外，
OnLaunched里不要假设窗口一定存在——多实例模式下可能复用已有窗口，
args.PreviousExecutionState == ApplicationExecutionState.Terminated才适合恢复状态；而
Suspending事件里不能做耗时 IO，否则系统会强制终止进程。
真正麻烦的是调试时热重载不生效，或者 XAML 更改后没反应——这通常是因为项目属性中
Enable XAML Hot Reload没勾选，或者你正在用 Release 配置运行。这些细节不报错，但会让开发节奏卡住很久。
