Avalonia 的 AppBuilder 必须在 Main 线程调用，因其初始化依赖 UI 线程同步上下文，跨线程调用 Start() 会抛 InvalidOperationException；Windows 可能“看似运行”但事件丢失，macOS/Linux 则直接崩溃或黑屏。
为什么 Avalonia 的 AppBuilder 必须在 Main 线程调用？
因为 Avalonia 初始化依赖 UI 线程的同步上下文，跨线程调用 AppBuilder.Start 会导致 InvalidOperationException: Cannot create platform window on non-UI thread。这不是 Windows 特有，macOS 和 Linux 同样报错。
- Windows 下可能“看似能跑”，但窗口句柄创建失败，后续事件（如点击、键盘）全丢失
- Linux（X11/Wayland）和 macOS（Cocoa）对线程模型更严格，直接崩溃或黑屏
- 别在
Task.Run或后台线程里启动 App —— 即使加了.ConfigureAwait(false)也没用 - 正确姿势：确保
Program.Main是同步入口，且未被任何 async/await 包裹（除非你明确用了Application.Initialize+Application.Run分离初始化与运行）
Window 构造后不显示？检查 Show() 和 Activate() 调用时机
Avalonia 不像 WinForms 那样构造即显示。new MainWindow().Show() 只是注册窗口并触发渲染调度，但若此时 App 尚未进入主循环（Application.Run() 没执行），窗口会静默丢弃。
- 常见错误：在
App.OnFrameworkInitializationCompleted里 new Window 但没调Show()，或者调了但Application.Current?.MainWindow还是 null - 推荐写法：
Application.Current?.MainWindow = new MainWindow(); Application.Current?.MainWindow?.Show();，且必须在OnFrameworkInitializationCompleted内完成 - macOS 上如果只调
Show()不调Activate()，窗口可能藏在 Dock 后面，用户看不到 —— 加一句Activate()更稳妥 - Linux Wayland 下，
Show()前若未设置Width/Height，窗口可能缩成 1×1 像素，调试时注意检查尺寸是否为 0
资源字典（Styles.xaml）加载失败的三个典型原因
Avalonia 查找资源字典路径依赖程序集的 AssemblyName 和文件嵌入方式，不是简单按文件名找。
- 没设
Build Action = "AvaloniaResource"：VS 默认是None或Content，导致编译后缺失，运行时报Resource not found: resm:MyApp.Styles.xaml?assembly=MyApp - 路径拼写含大小写错误：Linux/macOS 文件系统区分大小写，
styles.xaml≠Styles.xaml；务必和resm:后的路径完全一致 - 跨项目引用时没指定完整程序集名：比如样式在
MyApp.Themes程序集中，resm:MyApp.Themes.Styles.xaml?assembly=MyApp.Themes缺少?assembly=xxx就会找不到 - 调试技巧：用
dotnet publish -r linux-x64后进 publish 目录，用unzip -l MyApp.dll | grep Styles看资源是否真被打包进去了
绑定命令（ICommand）不响应点击？重点查 CanExecute 和 DataContext 继承链
Avalonia 的命令绑定比 WPF 更敏感，CanExecute 返回 false 时按钮不仅禁用，连点击事件都不触发 —— 很多开发者误以为是事件没挂上。
- 默认
RelayCommand构造时不传canExecute参数，等价于CanExecute恒为 false，按钮永远灰掉 -
DataContext在UserControl或ControlTemplate中容易断裂：比如ItemsControl的DataTemplate里 Button 的DataContext是当前 item，不是 ViewModel，导致命令找不到 - 避免用
{Binding #myCommand}这种相对绑定，Avalonia 解析不稳定；改用{Binding $parent[Window].DataContext.MyCommand}或显式Source={RelativeSource AncestorType=Window} - 调试方法：在
CanExecute方法里打断点，或临时返回true看按钮是否变亮 —— 如果变亮，问题就出在逻辑判断里
事情说清了就结束。跨平台 UI 最麻烦的从来不是写代码，而是每个平台偷偷改规则又不告诉你。
