graph_models生成空白或报错，主因是默认不递归解析外键且仅扫描指定app；需显式列出app、安装Graphviz、配置中文字体，并组合--verbose-names、--arrow-shape等参数才能生成含字段与关系的可用拓扑图。
django-extensions 的 graph_models 命令为什么生成空白或报错？
直接运行 python manage.py graph_models 很可能输出空图、报错或只画出极少数模型，根本原因是它默认不递归解析外键关系，也不自动包含所有 app。Django-extensions 默认只扫描当前命令指定的 app，且对抽象基类、Proxy 模型、未注册到 admin 的模型容易漏掉。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 必须显式列出要绘图的 app，例如
python manage.py graph_models auth profiles core -o models.png，不能依赖通配符或省略 - 加上
--include-models参数可强制包含特定模型（尤其当模型在非标准位置或被 import 逻辑隐藏时） - 若用抽象基类（如
class BaseModel(models.Model)），需加--group-models或手动在INSTALLED_APPS中确保其所在 app 已启用 - 报
GraphvizError: failed to execute ['dot']是因系统没装 Graphviz，不是 Django 配置问题；macOS 用brew install graphviz，Ubuntu 用apt install graphviz
如何让生成的拓扑图显示外键字段和关系方向？
默认图里只有模型框和连线，不标字段名、不区分一对一/一对多/多对多，导致无法判断关联逻辑。关键在启用 --verbose-names 和 --pygraphviz（或 --graphviz）组合，并配合关系标注参数。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 加
--verbose-names让字段显示user: User而非user_id: IntegerField - 加
--arrow-shape solid（默认是 line）+--rankdir TB（从上到下布局）提升可读性 - 用
--only-related可收缩图范围：只画当前 app 内模型之间的真实外键引用，避免把 auth.User 这类跨 app 引用全摊开 - 若想标出具体字段，必须加
--group-models+--disable-sorting，否则字段顺序会被重排打乱
生成 SVG/PNG 失败或中文乱码怎么办？
常见现象是输出文件为空、提示 encoding error，或中文字段名变成方块。这不是 Django-extensions 本身的问题，而是 Graphviz 渲染层缺失中文字体支持。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- Linux/macOS 下，创建
/usr/local/etc/graphviz/config6.conf（路径依 Graphviz 版本而异），加入：fontname="Noto Sans CJK SC" fontsize=12
，然后重装或重启 Graphviz 服务 - Windows 用户更简单：下载并安装
NotoSansCJKsc-Regular.otf到系统字体目录，再在命令中显式指定：--fontname "Noto Sans CJK SC" - 避免用
-o models.jpg—— Graphviz 原生不支持 JPG，只认png、svg、pdf；用svg格式最稳妥，缩放不失真 - 如果用 PyCharm 或 VS Code 终端运行失败，换系统原生命令行（尤其是 Windows 的 PowerShell），某些 IDE 终端会截断 Graphviz 的 stderr 输出，掩盖真实错误
graph_models 和 Django Debug Toolbar 的模型图有什么区别？
Debug Toolbar 的 “SQL” 或 “Models” 面板只显示当前请求涉及的模型实例和查询链路，是运行时快照；graph_models 是静态代码分析结果，反映整个项目 models.py 的定义结构。两者完全不重叠，也不能互相替代。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 用
graph_models查“设计是否合理”：比如发现User被 12 个模型外键引用却没加db_index=True，或循环依赖（A → B → C → A） - 别指望它反映
select_related或prefetch_related的实际加载行为——那些是 ORM 运行时优化，不在 AST 解析范围内 - CI/CD 中可加校验步骤：
python manage.py graph_models --check --fail-on-empty，防止新提交引入零模型 app 导致部署后管理界面异常
