中文乱码主因是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属性，明确告诉它“该用什么字体”：
<Button FontFamily="Microsoft YaHei, SimSun, sans-serif">登录</Button><TextBlock FontFamily="Microsoft YaHei UI">欢迎使用</TextBlock>- 推荐写成字体列表形式（逗号分隔），让系统按顺序 fallback，比如
"Microsoft YaHei, SimHei, SimSun, sans-serif" - 注意：XAML里引号要匹配，别漏掉双引号；Browser环境下仅靠这个可能不够，需配合全局注册
全局字体资源定义（统一管理）
在App.axaml的<Application.Resources>里声明一个可复用的字体资源，再用{DynamicResource}引用：
- 添加资源定义：
<Application.Resources><br> <FontFamily x:Key="ChineseFont">Microsoft YaHei, SimHei, SimSun, sans-serif</FontFamily><br></Application.Resources>
- 在任意控件中使用：
<TextBlock FontFamily="{DynamicResource ChineseFont}" Text="测试中文"/> - Window级也可统一设：
<Window FontFamily="{DynamicResource ChineseFont}"> - 此方式便于后期统一替换品牌字体，但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中定义资源：<FontFamily x:Key="BrandFont">avares://YourApp/Assets/Fonts/SourceHanSansCN-Regular.otf</FontFamily> - 务必检查构建动作：字体文件的
Build Action要设为Content，且Copy to Output Directory设为Copy if newer
基本上就这些。核心逻辑很清晰：Browser环境靠预置或注册字体文件 + 合理fallback链；桌面端更宽松，但统一设置仍能避免平台差异。选哪种方案，取决于你用的是主分支还是font分支、是否需要定制字体、以及项目所处阶段。
