ScottPlot在Docker中显示中文乱码问题的解决方案

问题背景

在使用ScottPlot图表库时，开发者发现当应用程序运行在Docker容器中时，所有非英文字符（如中文、日文、韩文）都会显示为方框（俗称"豆腐块"）。这个问题在Windows和Mac系统上运行正常，仅在Docker环境中出现。

根本原因分析

经过技术排查，发现这是由于Docker基础镜像（如mcr.microsoft.com/dotnet/aspnet:6.0）默认不包含中文字体支持导致的。具体表现为：

1. 字体检测机制失效：SKFontManager.Default.MatchCharacter('汉')返回null
2. 自动字体选择失败：myPlot.Font.Automatic()无法正确识别中文字符
3. 系统缺少必要的字体渲染库

完整解决方案

1. 准备中文字体文件

首先需要获取合法可用的中文字体文件（如微软雅黑、思源黑体等）。可以从以下位置获取：

• Windows系统：C:\Windows\Fonts目录
• Linux系统：/usr/share/fonts/目录 可以使用fc-list :lang=zh命令查看已安装的中文字体

2. 修改Dockerfile配置

FROM mcr.microsoft.com/dotnet/aspnet:6.0

# 设置时区
ENV TZ=Asia/Shanghai
RUN ln -snf /usr/share/zoneinfo/$TZ /etc/localtime && echo $TZ > /etc/timezone

# 安装字体相关依赖
RUN apt-get update && apt-get install -y \
    libfreetype6 \
    libfontconfig1 \
    fontconfig

# 拷贝中文字体到容器
COPY ./fonts/* /usr/share/fonts/truetype/

# 刷新字体缓存
RUN fc-cache -vf

WORKDIR /app
COPY ./publish /app
CMD ["dotnet", "YourApp.dll"]

3. 代码层调整

在ScottPlot使用代码中，需要显式指定中文字体：

// 创建图表
Plot myPlot = new();

// 添加数据
var sig1 = myPlot.Add.Signal(Generate.Sin(phase: .1));
sig1.LegendText = "测试数据";

// 显式设置中文字体（需替换为实际字体名）
myPlot.Font.Set("Microsoft YaHei");  // 或 "SimHei", "Source Han Sans"等

// 其他图表配置...
myPlot.SavePng("output.png", 800, 600);

技术原理深入

1. 字体渲染机制：ScottPlot底层使用SkiaSharp进行文字渲染，需要操作系统提供字体支持
2. Docker环境特点：基础镜像通常只包含最小化系统，不包含额外字体
3. 字体匹配流程：当系统找不到合适字体时，会回退到默认字体（通常不支持中文）

最佳实践建议

1. 字体选择：推荐使用开源字体如"思源黑体"(Source Han Sans)避免版权问题
2. 多语言支持：如果需要同时显示多种语言，可以使用支持多语言的字体
3. 字体缓存：在Docker构建时执行fc-cache -vf确保字体被正确识别
4. 字体验证：在容器内执行fc-list命令验证字体是否安装成功

常见问题排查

如果按照上述步骤操作后仍存在问题，可以检查：

1. 字体文件权限是否正确（应设为644）
2. 字体文件是否完整无损坏
3. 是否所有依赖库（libfreetype6等）已正确安装
4. 字体名称是否正确（可通过fc-list查看实际字体名）