Avalonia是一个基于.NET的跨平台UI框架，底层使用Skia作为渲染引擎。在Windows上开发时，界面字体显示一切正常，但把程序发布到Linux服务器或桌面环境后，经常会遇到界面文字全部变成方块、中文显示乱码，甚至程序启动时抛出字体相关异常的情况。这个问题的根源在于Linux系统的字体生态与Windows完全不同，Avalonia默认的字体查找策略在Linux上经常找不到合适的字体。本文将从原理到实践，系统地讲清楚如何在Linux上彻底解决Avalonia的字体问题。
为什么Avalonia在Linux上容易出现字体问题
首先要理解Avalonia的渲染机制。Avalonia使用Skia绘制文本，而Skia在Linux上通过FontConfig库来枚举和匹配系统字体。Windows系统默认自带宋体、微软雅黑等中文字体，所以你在XAML里不写任何字体配置，中文也能正常渲染。但Linux发行版出于体积和授权考虑，最小安装往往只带有DejaVu Sans这类西文字体，一个中文字形都没有。
当Skia找不到请求的字体时，会触发字体回退（fallback）逻辑，尝试用其他字体绘制字符。如果整个回退链上都没有中文字形，中文字符就会显示为空白或方块。更严重的情况是，某些精简版Linux（比如Docker镜像）连fontconfig都没安装，此时Avalonia启动阶段就可能直接抛异常，提示无法加载默认字体管理器。
还有一个容易被忽略的点：你在XAML里写了FontFamily="Microsoft YaHei"，这个字体名只在Windows上有效。Linux上即使安装了文泉驿或Noto中文字体，名字也对不上，等于白配。所以解决问题的核心思路只有两条：要么让目标Linux系统拥有你需要的字体，要么让程序自带字体、不依赖系统。
方案一：在Linux系统上安装中文字体
如果你的应用运行在有完整桌面环境的Linux上，最直接的办法是安装中文字体包。以Ubuntu和Debian为例，执行以下命令即可：
sudo apt update sudo apt install fonts-noto-cjk fonts-wqy-zenhei fontconfig fc-cache -fv
CentOS或RHEL系的系统可以使用dnf或yum安装：
sudo dnf install google-noto-sans-cjk-ttc-fonts fontconfig fc-cache -fv
安装完成后，执行fc-list :lang=zh可以查看系统当前支持中文的字体列表。如果列表不为空，重新启动Avalonia应用，中文一般就能正常显示了。这个方案适合你能控制目标机器环境的场景，比如公司内部部署的工控机或服务器。
但它的缺点也很明显：你无法要求每一个最终用户都手动装字体。特别是通过Docker分发应用时，基础镜像里往往什么字体都没有。对于Docker环境，可以在Dockerfile中追加字体安装步骤：
FROM mcr.microsoft.com/dotnet/runtime:8.0
RUN apt-get update && \
apt-get install -y fontconfig fonts-noto-cjk && \
rm -rf /var/lib/apt/lists/*
方案二：将字体文件嵌入程序集随应用分发
更稳妥的做法是不依赖系统字体，把ttf文件直接打进程序里。首先把字体文件（例如SourceHanSansSC-Regular.otf或任意开源中文字体）复制到项目目录，并确认文件的生成操作为嵌入资源。在项目文件中这样配置：
<ItemGroup> <EmbeddedResource Include="Assets\SourceHanSansSC-Regular.otf" /> </ItemGroup> <ItemGroup> <PackageReference Include="Avalonia.Skia" Version="11.0.10" /> </ItemGroup>
注意上面的路径中使用了反斜杠，这是Windows相对路径的标准写法，发布到Linux时.NET会自动处理路径分隔符，不需要手动改成斜杠。嵌入资源后，Avalonia从11版本开始支持用特殊的URI格式直接引用程序集内字体：
<Window xmlns="https://github.com/avaloniaui"
FontFamily="avares://YourApp/Assets/SourceHanSansSC-Regular.otf#思源黑体">
<TextBlock Text="中文字体测试"/>
</Window>
URI中的#后面是字体的实际家族名，必须与字体文件内部定义的名称一致，写错了同样会加载失败。如果不想在每个控件上重复设置，可以在App.axaml的Application级别统一指定默认字体，也可以通过主题资源覆盖来设置。
方案三：自定义FontManager实现精细控制
当嵌入字体方案在Linux上仍然表现异常，或者你需要更精细的字体回退控制时，可以重写Avalonia的字体管理器。核心思路是从程序集加载字体流，创建自定义的Typeface，然后交给Skia使用。先定义一个自定义的FontManagerImpl：
using Avalonia.Media;
using Avalonia.Platform;
using Avalonia.Skia;
using SkiaSharp;
public class CustomFontManagerImpl : IFontManagerImpl
{
private readonly Typeface[] _customTypefaces;
private readonly Typeface _defaultTypeface;
public CustomFontManagerImpl()
{
// 从程序集加载内嵌字体
using var stream = typeof(App).Assembly.GetManifestResourceStream(
"YourApp.Assets.SourceHanSansSC-Regular.otf");
using var skStream = new SKManagedStream(stream);
using var typeface = SKTypeface.FromStream(skStream);
_customTypefaces = new[] { new Typeface(typeface.FamilyName) };
_defaultTypeface = new Typeface(typeface.FamilyName);
}
public string GetDefaultFontFamilyName() => _defaultTypeface.FontFamily.Name;
public IEnumerable<string> GetInstalledFontFamilyNames(bool checkForUpdates = false)
=> _customTypefaces.Select(t => t.FontFamily.Name);
public bool TryMatchCharacter(int codepoint, FontStyle fontStyle, FontWeight fontWeight,
FontStretch fontStretch, string? culture, out Typeface typeface)
{
typeface = _defaultTypeface;
return true;
}
public IGlyphTypefaceImpl CreateGlyphTypeface(Typeface typeface)
{
using var stream = typeof(App).Assembly.GetManifestResourceStream(
"YourApp.Assets.SourceHanSansSC-Regular.otf");
var skTypeface = SKTypeface.FromStream(stream);
return new GlyphTypefaceImpl(skTypeface);
}
public void Dispose() { }
}
然后在Program.cs或App初始化阶段，通过AppBuilder把这个实现注册进去：
public static AppBuilder BuildAvaloniaApp()
=> AppBuilder.Configure<App>()
.UsePlatformDetect()
.With(new SkiaOptions { CustomFontManagerImpl = typeof(CustomFontManagerImpl) })
.LogToTrace();
}
这个方案的好处是完全绕开了系统的fontconfig，程序在任何Linux环境下的字体行为都一致，包括Docker容器、树莓派等精简环境。缺点是需要处理的细节多一点，比如TryMatchCharacter方法的回退逻辑，如果有条件，建议在默认字体之外再嵌入一个英文字体，针对不同码位返回不同的Typeface，中英文混排效果会更好。
字体选择与发布部署的注意事项
选择嵌入字体时务必注意版权。微软雅黑是商业授权字体，不能随应用分发，建议使用思源黑体、思源宋体、Noto Sans CJK、文泉驿等开源字体，这些字体在OFL等宽松协议下允许自由分发和商用嵌入。
发布时还要检查自包含发布（self-contained）的输出目录，确认otf或ttf文件确实被复制到了输出路径或嵌入到了程序集中。如果用dotnet publish -r linux-x64发布，可以在目标机器上先用fc-list排查系统字体，再通过环境变量AVALONIA_SCREEN_SCALE_FACTOR等调试手段验证渲染配置是否生效。遇到启动即崩溃的场景，优先确认目标系统是否安装了fontconfig库，缺了它Skia的默认字体管理器会初始化失败。
最后给一个简单的排查顺序总结：先在目标Linux上执行fc-list :lang=zh确认系统中文字体情况；有字体但仍乱码，检查XAML中的FontFamily名称是否与实际字体名匹配；追求零依赖分发则直接采用嵌入字体加自定义FontManager的方案。按这个思路走下来，Avalonia应用在各个Linux发行版上都能稳定显示中英文内容。