MySQL Workbench 导出 ER 图为 PDF 空白或报错，根本原因是未配置 Graphviz 的 dot 路径；需安装 Graphviz、将 dot 加入 PATH，并在 Workbench 偏好设置中手动指定其绝对路径，导出前还需点击画布获取焦点。
用 mysql-workbench 导出 ER 图为 PDF 时空白或报错
常见现象是点击 export as png/pdf 后生成空文件，或弹出 cannot export diagram: no valid output path 错误。根本原因不是权限或路径名含空格，而是 workbench 默认禁用了外部图形导出依赖——它需要系统级的 graphviz 支持，但安装后不配置就等于没装。
- 确认已安装
Graphviz（macOS 用brew install graphviz，Windows 下载官方 installer 并勾选「Add Graphviz to the system PATH」） - 启动
mysql-workbench前，在终端先运行which dot，确保返回有效路径；若无输出，说明 PATH 没生效，需重启 Workbench 或重开终端 - Workbench 设置里必须手动指定：
Preferences → Modeling → Export → Graphviz DOT Path，填入dot的绝对路径（例如 macOS 是/opt/homebrew/bin/dot，Windows 是C:\Program Files\Graphviz2.44\bin\dot.exe） - 导出前务必先「选中画布任意位置」再操作，否则会静默失败——这是 UI 层的焦点 bug，不是模型问题
dbdiagram.io 在线工具导出 PDF 字体乱码或中文消失
这是典型的字体嵌入缺失问题。dbdiagram.io 渲染依赖浏览器 Canvas，而 Canvas 默认不嵌入中文字体，导出 PDF 时直接丢弃无法渲染的字符。
- 临时解法：在 Chrome 中打开页面后，按
Ctrl+P（Win）或Cmd+P（Mac），选择「另存为 PDF」，此时浏览器会走本地 PDF 渲染引擎，中文字体正常 - 长期规避：避免在表名/字段名里用中文；改用英文加下划线（如
user_profile），既符合建模规范，也绕过所有字体问题 - 注意
dbdiagram.io不支持外键自动连线，如果模型里有FOREIGN KEY但没手动拖线，导出图里不会显示关系箭头——这不是导出问题，是建模漏操作
用 sqlacodegen + eralchemy 生成带注释的 PDF ER 图
适合已有数据库、想从真实 schema 反向生成带业务注释的 PDF。关键在于注释能否落地：MySQL 的 COMMENT 字段能被读取，但 PostgreSQL 的 COMMENT ON COLUMN 需要额外参数才能提取。
- 先用
sqlacodegen生成 ORM 模型：sqlacodegen mysql://user:pass@localhost/dbname --outfile models.py - 再用
eralchemy渲染：eralchemy render -i models.py -o erd.pdf - 如果字段注释没出现，检查
models.py里对应字段是否含comment=参数；没有的话，eralchemy就看不到——它不连接数据库，只解析 Python 文件 - PDF 页面尺寸固定为 A4，若模型过大导致缩放失真，可先导出为
.png再用convert转 PDF：convert -density 300 erd.png erd.pdf
团队协作时 PDF ER 图版本和源模型不同步
PDF 是快照，不是活文档。最常踩的坑是：开发改了 CREATE TABLE 语句，但忘了重新导出 PDF，结果评审时拿的是旧图，字段类型对不上。
- 把导出命令写进
Makefile或package.jsonscripts，例如："erd:pdf": "eralchemy render -i models.py -o docs/erd-$(date +%Y%m%d).pdf" - PDF 文件名里强制带日期或 Git commit hash，避免覆盖；不要用
erd.pdf这种静态名 - 真正关键的是「谁负责触发更新」：建议由 CI 流水线在每次合并到
main后自动生成新 PDF 并推送到文档站，人手导出必然遗漏 - PDF 本身不支持超链接跳转到具体表，所以别指望靠它查细节；它只承担「共识对齐」作用，查字段还得看 SQL 或代码
ER 图导出不是终点，而是模型和实现之间那层薄纸——纸可以印得很漂亮，但一旦两边没对齐，再高清的 PDF 也只是精致的幻觉。
