中文乱码主因是Avalonia（尤其Ursa.Avalonia）默认不打包中文字体，Browser/WebAssembly环境缺乏fallback字体链；解决关键为：用对字体、设对位置、适配环境，含切font分支、控件级指定、全局资源定义及自定义字体引入四方案。

中文乱码在Avalonia（尤其是Ursa.Avalonia）中，根本原因不是代码写错了，而是默认不打包中文字体——尤其在Browser/WebAssembly环境下，系统可用字体有限，又没 fallback 字体链，一碰到缺字就显示方块或乱码。解决关键就三点：用对字体、设对位置、适配环境。

直接切font分支（新手首选）

项目团队已维护好一个开箱即用的font分支，里面预置了微软雅黑、宋体、思源黑体等常用中文字体资源，无需改代码、不调配置，切过去就生效：

• 终端执行：git clone https://gitcode.com/IRIHI_Technology/Ursa.Avalonia && cd Ursa.Avalonia && git checkout font
• 如果你是引用Ursa.Avalonia作为子模块或NuGet包，建议直接基于该分支构建本地包
• 适合新项目启动、Demo验证、快速交付，5分钟内搞定

控件级字体指定（灵活可控）

不换分支也能修，给具体控件加FontFamily属性，明确告诉它“该用什么字体”：

• 登录
• 欢迎使用
• 推荐写成字体列表形式（逗号分隔），让系统按顺序 fallback，比如"Microsoft YaHei, SimHei, SimSun, sans-serif"
• 注意：XAML里引号要匹配，别漏掉双引号；Browser环境下仅靠这个可能不够，需配合全局注册

全局字体资源定义（统一管理）

在App.axaml的里声明一个可复用的字体资源，再用{DynamicResource}引用：

• 添加资源定义：

  Microsoft YaHei, SimHei, SimSun, sans-serif

• 在任意控件中使用：
• Window级也可统一设：
• 此方式便于后期统一替换品牌字体，但Browser环境仍需确保字体文件实际加载成功

自定义字体文件引入（企业/品牌需求）

要用思源黑体、阿里巴巴普惠体等开源字体，或公司定制字体，就得手动引入.ttf/.otf文件：

• 把字体文件放进Assets/Fonts/目录（如Assets/Fonts/SourceHanSansCN-Regular.otf）
• 在App.axaml.cs的OnFrameworkInitializationCompleted中注册：

FontManager.Current.AddFontResource(new Uri("avares://YourApp/Assets/Fonts/SourceHanSansCN-Regular.otf"));

• 再在App.axaml中定义资源：avares://YourApp/Assets/Fonts/SourceHanSansCN-Regular.otf
• 务必检查构建动作：字体文件的Build Action要设为Content，且Copy to Output Directory设为Copy if newer

基本上就这些。核心逻辑很清晰：Browser环境靠预置或注册字体文件 + 合理fallback链；桌面端更宽松，但统一设置仍能避免平台差异。选哪种方案，取决于你用的是主分支还是font分支、是否需要定制字体、以及项目所处阶段。