plantuml插件预览失败、中文乱码、快捷键无效，主因是配置缺失或冲突：需确保仅安装jebbs官方插件、文件后缀为.puml、设置plantuml.server为https://www.plantuml.com/plantuml并设render为plantumlserver，中文加skinparam defaultfontname "noto sans cjk sc"。
PlantUML插件在VSCode中默认不启用远程渲染，时序图预览失败、中文乱码、快捷键无效——这些问题基本都源于配置缺失或冲突，不是插件本身坏了。
为什么Alt+D没反应？检查插件激活状态和快捷键绑定
VSCode里Alt+D（macOS为Option+D）是PlantUML插件的默认预览快捷键，但经常失效。常见原因有：已安装多个PlantUML相关插件（如同时装了plantuml和plantuml-previewer），造成命令冲突；或快捷键被其他插件（比如Markdown All in One）劫持。
- 打开命令面板（
Ctrl+Shift+P），输入Preferences: Open Keyboard Shortcuts (JSON)，检查是否有重复绑定plantuml.preview的条目 - 卸载所有非
jebbs.plantuml的PlantUML类插件，只保留官方维护版本 - 确认当前文件后缀是
.puml或.pu，否则插件不会注册对应命令
plantuml.server必须配，否则本地Java/Graphviz配置全是白忙
新版PlantUML插件（v2.17+）默认尝试调用本地plantuml.jar，但多数人没装JDK或Graphviz，或版本不兼容（比如JDK 25需搭配PlantUML 1.2025.3+）。直接走官方服务器是最稳的方案。
- 在VSCode设置中搜索
plantuml.server，填入https://www.plantuml.com/plantuml - 同步设置
plantuml.render为PlantUMLServer（不是Local） - 删掉
plantuml.java、plantuml.graphvizDot等本地路径配置项，避免干扰
中文时序图显示方块？加skinparam defaultFontName就行
默认渲染下，中文会变成□□，因为PlantUML服务端用的是Linux字体环境，不带中文字体。不需要改服务器或装字体，一行配置就能解决。
- 在
.puml文件开头添加：@startuml skinparam defaultFontName "Noto Sans CJK SC" Alice -> Bob: 查询用户信息 Bob --> Alice: 返回User对象 @enduml
- 推荐字体名：
Noto Sans CJK SC（简体）、Noto Sans CJK TC（繁体），服务端已内置；避免用SimSun或Microsoft YaHei，这些在服务端不存在 - 如果团队用Mac或Windows本地渲染，才需要额外配
plantuml.java路径并指定本地字体
时序图导出SVG后缩放模糊？别用PNG，优先选svg格式
导出为PNG看似方便，但放大后边缘发虚，尤其嵌入Confluence或PDF文档时明显。SVG是矢量格式，缩放无损，且文件体积更小。
- 右键预览窗口 →
Export Current Diagram→ 选svg格式保存 - 若需批量导出整个项目下的所有时序图，配置
plantuml.exportFormat为svg，再用命令面板运行PlantUML: Export All Diagrams - 注意：SVG不支持透明背景，如需白底，加
skinparam backgroundColor white
真正卡住人的从来不是语法，而是渲染链路里某一层没对齐——服务器地址、字体名、文件后缀、插件唯一性，四个点里错一个，时序图就出不来。先砍掉所有“可能有用”的插件和配置，从最简.puml文件 + plantuml.server起步，比反复调Java路径快得多。
