PlantUML中文乱码如何解决？

Question

在使用PlantUML绘制UML图时，常遇到中文显示为方框或乱码的问题，尤其在导出为PNG或SVG格式时更为明显。该问题通常源于Java运行环境默认字体不支持中文，或PlantUML未正确指定中文字体。如何配置PlantUML以正确渲染中文，成为开发者在中文环境下使用该工具的一大困扰。需从JVM字体支持、系统字体配置及PlantUML代码层面综合排查解决。

Answer 1

一、问题背景与现象分析

在使用PlantUML绘制UML图时，中文显示异常（如方框、乱码）是开发者在中文操作系统或国际化项目中频繁遇到的问题。该问题主要出现在导出为PNG或SVG格式时，而文本编辑器内预览可能正常，这说明渲染阶段存在字体缺失或映射错误。

根本原因通常归结为以下三点：

• JVM运行环境未加载支持中文的系统字体；
• 操作系统缺少常用中文字体（如宋体、微软雅黑）；
• PlantUML未显式指定中文字体名称或字体路径。

尤其在Linux服务器环境下无GUI组件时，字体资源更易缺失，导致图像生成失败或字符替换为空白/方块。

二、排查路径：由浅入深的技术层级分析

层级	检查项	常见表现	验证方法
应用层	PlantUML是否指定中文字体	中文被替换成矩形	查看代码是否含skinparam defaultFontName
运行时	JVM可用字体列表	日志提示“No such font”	执行GraphicsEnvironment.getLocalGraphicsEnvironment().getAllFonts()
系统层	操作系统安装中文字体	命令行无法找到SimSun等字体	Linux下查看/usr/share/fonts目录内容
输出层	导出格式差异（PNG vs SVG）	PNG乱码而SVG正常	对比不同格式输出结果

三、解决方案汇总

1. 方案一：PlantUML代码中显式设置字体

   skinparam defaultFontName 微软雅黑
   skinparam classAttributeFontName 微软雅黑
   skinparam noteFontName 宋体

   此方式适用于所有基于Graphviz布局的场景，确保PlantUML优先调用指定字体。
2. 方案二：启动JVM时指定字体目录

   java -Djava.awt.headless=true \
        -Dsun.java2d.fontpath=/usr/share/fonts/truetype \
        -jar plantuml.jar diagram.pu

   特别适用于无图形界面的Linux服务器环境。
3. 方案三：安装中文字体到系统 在Debian/Ubuntu系统上可执行：

   sudo apt-get install fonts-wqy-zenhei
   sudo fc-cache -fv

   然后通过fc-list :lang=zh确认字体注册成功。
4. 方案四：使用Docker镜像内置字体支持 构建自定义Docker镜像，集成中文字体和PlantUML：

   FROM plantuml/plantuml-server:latest
   COPY msyh.ttc /usr/local/share/fonts/
   RUN fc-cache -fv

四、自动化检测流程图

graph TD
    A[开始] --> B{是否存在中文乱码?}
    B -- 是 --> C[检查PlantUML是否指定中文字体]
    C --> D{已指定字体?}
    D -- 否 --> E[添加skinparam defaultFontName]
    D -- 是 --> F[检查JVM字体环境]
    F --> G[运行Java程序列出所有字体]
    G --> H{包含中文字体?}
    H -- 否 --> I[安装中文字体到系统]
    H -- 是 --> J[确认导出格式兼容性]
    J --> K[测试PNG/SVG输出]
    K --> L[问题解决]
    E --> L
    I --> G
  

五、高级配置建议与最佳实践

对于企业级CI/CD流水线中的PlantUML自动化渲染，推荐采用统一字体策略：

• 统一使用WenQuanYi Micro Hei或Noto Sans CJK SC等开源字体，避免版权问题；
• 在Maven或Gradle插件中嵌入字体路径参数；
• 对SVG输出启用&useBrailleFont=false防止转码干扰；
• 定期清理字体缓存，避免旧版本冲突；
• 结合plantuml.config.properties文件全局配置默认字体；
• 在Kubernetes部署中挂载ConfigMap存储字体文件；
• 利用-enablestats选项监控字体加载耗时；
• 针对高DPI输出设置-Dprism.allowhidpi=false提升清晰度；
• 使用!ifdef条件语句实现多语言字体切换；
• 记录每次渲染使用的JVM版本与字体列表用于审计追踪。