AppBuilder.Start()必须在Main线程调用，否则跨平台行为不一致：Windows丢失输入事件，macOS/Linux立即崩溃；Window.Show()需在OnFrameworkInitializationCompleted中执行并显式设置尺寸和Activate；Styles.xaml加载要求Build Action为AvaloniaResource、路径大小写严格匹配、assembly名完整。
AppBuilder.Start() 必须在 Main 线程调用
跨线程启动 Avalonia 应用会直接抛 InvalidOperationException: Cannot create platform window on non-UI thread，不是“偶尔出错”，而是平台行为不一致导致的硬性失败。
Windows 可能勉强创建窗口句柄，但所有输入事件（点击、键盘、焦点）全部丢失；macOS 和 Linux（尤其是 Wayland）会立即崩溃或黑屏，连日志都来不及输出。
- 绝对不要在
Task.Run、ThreadPool.QueueUserWorkItem或任何async Main的 await 后调用AppBuilder.Start<app>()</app> - 即使加了
.ConfigureAwait(false)也无效 —— 这不是同步/异步问题，而是 UI 线程上下文缺失 - 正确入口写法：保持
Program.Main是同步方法，且不包裹await；若需异步初始化逻辑，改用Application.Initialize()+Application.Run()分离模式
Window.Show() 后窗口不显示？检查三个关键时机
Avalonia 不自动激活或调度主循环外的窗口，new MainWindow().Show() 只是注册渲染任务，不是“立刻弹窗”。
常见现象：程序跑起来没报错，但桌面空空如也；调试时 Application.Current?.MainWindow 为 null；macOS 下窗口藏在 Dock 后面不可见。
- 必须在
App.OnFrameworkInitializationCompleted回调内完成窗口实例化与显示，不能提前到构造函数或静态初始化器里 - 推荐写法：
Application.Current?.MainWindow = new MainWindow(); Application.Current?.MainWindow?.Show(); Application.Current?.MainWindow?.Activate();——Activate()对 macOS 是刚需 - Linux Wayland 下，
Show()前未设置Width/Height（哪怕设为800/600），窗口可能渲染为 1×1 像素，肉眼不可见
Styles.xaml 找不到？路径和嵌入方式必须严格匹配
资源字典加载失败不会抛异常，只会静默跳过样式，结果是控件还原成默认外观，极易被误判为“XAML 写错了”。
错误信息形如 Resource not found: resm:MyApp.Styles.xaml?assembly=MyApp，本质是三处不一致：
-
Build Action必须设为AvaloniaResource（不是Content或None），否则编译后根本不在程序集里 -
resm:后的路径大小写必须和实际文件名、命名空间完全一致 —— Linux/macOS 区分大小写，styles.xaml≠Styles.xaml - 跨项目引用时，
?assembly=后必须写完整程序集名（如MyApp.Themes），不能只写类库名或省略
Linux 下窗口缩成点？Wayland 和 X11 行为差异要盯死
同一段代码在 Ubuntu（Wayland 默认）上黑屏或闪退，在 X11 下正常，大概率是线程模型或窗口尺寸策略不兼容。
Wayland 协议禁止非 UI 线程操作窗口，且对初始尺寸更敏感；X11 容错稍高，但已逐步弃用。
- 确保
Window构造后、Show()前显式设置Width和Height（例如window.Width = 1024; window.Height = 768;） - 禁用 Wayland 强制走 X11 调试用：
export GDK_BACKEND=x11（GTK 应用）或export QT_QPA_PLATFORM=xcb（Qt 混合场景） - 不要依赖
WindowState = WindowState.Maximized初始化 —— Wayland 下可能触发布局循环，先设尺寸再最大化更稳
