PyCharm中PlantUML插件无法渲染中文

Question

在使用PyCharm配合PlantUML插件绘制UML图时，用户常遇到中文无法正常渲染的问题，表现为中文字体显示为方框或乱码。该问题通常源于PlantUML默认使用的字体不支持中文，或JVM未正确配置中文字符集。尤其在导出SVG或PNG图像时，若系统缺少合适的中文字体（如SimSun、Microsoft YaHei），则会导致渲染失败。此外，IntelliJ平台的图形渲染后端（如JavaFX或AWT）对非ASCII字符的支持有限，也加剧了此问题。需通过显式指定中文字体、修改PlantUML配置或调整IDE启动参数来解决。

Answer 1

解决PyCharm中PlantUML中文渲染乱码问题的深度剖析

1. 问题现象与初步定位

在使用PyCharm配合PlantUML插件绘制UML图时，用户常遇到中文无法正常渲染的问题。典型表现为：

• 类名、方法名或注释中的中文显示为“□□”方框；
• 导出PNG/SVG图像后，中文部分出现乱码或空白；
• 预览窗口与实际导出结果不一致。

该问题并非PlantUML逻辑错误，而是图形渲染链路中字体与字符集支持缺失所致。

2. 根本原因分析：从底层机制切入

PlantUML基于Java运行，其图像生成依赖JVM的图形渲染系统（AWT/Swing或JavaFX）。中文渲染失败的根本原因可归结为以下三层：

层级	组件	问题描述
1	JVM字体配置	默认字体（如Dialog、SansSerif）可能映射到不支持中文的物理字体
2	操作系统字体库	缺少SimSun、Microsoft YaHei等中文字体文件
3	IntelliJ渲染后端	AWT在Headless模式下对非ASCII字符支持有限

3. 解决方案路径图谱

根据问题层级，解决方案应逐层推进。以下是推荐的处理流程：

        graph TD
            A[发现中文乱码] --> B{检查系统字体}
            B -->|缺少中文字体| C[安装SimSun或YaHei]
            B -->|已有字体| D[配置PlantUML字体]
            D --> E[设置JVM启动参数]
            E --> F[重启PyCharm验证]
            F --> G[导出SVG/PNG测试]
            G --> H[问题解决]
    

4. 具体实施步骤

以下为可操作性强的四步解决方案：

4.1 确保系统级中文字体可用

在Linux/macOS上可通过命令验证：

fc-list :lang=zh | grep -i "simsun\|yahei"

若无输出，则需手动安装宋体（SimSun.ttf）至~/.fonts/并刷新缓存：fc-cache -fv

4.2 显式指定PlantUML中文字体

在PlantUML源码中添加字体声明：

@startuml
skinparam defaultFontName "Microsoft YaHei"
class 用户 {
+String 姓名
+void 登录()
}
@enduml

支持的常见中文字体名称包括："SimSun", "KaiTi", "FangSong", "Microsoft YaHei"。

4.3 调整PyCharm的JVM启动参数

编辑pycharm.vmoptions文件（位于PyCharm安装目录的bin/下），添加：

-Dsun.java2d.fontpath=/usr/share/fonts
-Dawt.useSystemAAFontSettings=on
-Dswing.aatext=true

Windows用户可尝试指定字体路径：-Dsun.java2d.fontpath=C:\Windows\Fonts

4.4 使用Docker环境隔离验证

为排除本地环境干扰，可使用带中文字体的Docker镜像进行测试：

docker run -it --rm \\
-v $(pwd):/plantuml \
plantuml/plantuml:latest \
java -Djava.awt.headless=false -jar plantuml.jar example.puml

5. 高级调试技巧

对于复杂环境，建议启用PlantUML调试日志：

@startuml
debug fonts
class 测试 {
+String 中文字段
}
@enduml

该指令将输出字体匹配过程，便于判断是否成功加载目标中文字体。

6. 持续集成中的规避策略

在CI/CD流水线中，建议嵌入字体检查脚本：

#!/bin/bash
if ! fc-list :lang=zh | grep -q "SimSun"; then
echo "Error: 中文字体未安装"
exit 1
fi

结合Dockerfile预装字体，确保构建环境一致性。