Doxygen 生成 C++ 类图完整配置指南

Doxygen 结合 Graphviz 可以为 C++ 项目自动生成 UML 类图，但默认配置未启用图表功能，且 Doxyfile 配置项众多，网络上的教程多基于旧版本，直接沿用会在新版本中产生废弃选项警告。本文给出从环境准备到类图生成的完整配置，并逐项标注版本差异。配置在 Doxygen 1.8.17（Ubuntu 20.04 仓库版本）上验证，1.9.x 的差异见文中注释与第 8 节对照表，文末附完整配置模板。

1. 环境准备

1.1 必需工具

• Doxygen：源代码文档生成工具
• Graphviz：图形可视化软件包，提供 dot 命令用于图表渲染

1.2 安装方法

Linux（Ubuntu/Debian）：

sudo apt install doxygen graphviz

macOS（使用 Homebrew）：

brew install doxygen graphviz

Windows：

• 从 Doxygen 官网 下载安装程序
• 从 Graphviz 官网 下载安装程序
• 安装后需将 Graphviz 的 bin 目录添加到系统 PATH 环境变量

1.3 验证安装

doxygen -v    # 显示 Doxygen 版本
dot -V        # 显示 Graphviz 版本

2. 配置文件基础

在项目根目录执行 doxygen -g 生成默认配置文件 Doxyfile，再按后续各节修改。已有旧 Doxyfile 时可先执行 doxygen -u：该命令会将新版新增的选项补进文件，并标记废弃选项，减少手工比对的工作量。

2.1 基础项目配置

PROJECT_NAME           = "My Project"
PROJECT_BRIEF          = "项目简要描述"
OUTPUT_DIRECTORY       = ./docs
CREATE_SUBDIRS         = YES

2.2 源码扫描配置

INPUT                  = .
FILE_PATTERNS          = *.cpp *.h *.hpp *.cxx *.hxx *.cc *.hh
RECURSIVE              = YES
EXCLUDE_PATTERNS       = */test/* */build/* */cmake-build-*/*

2.3 文档提取配置

EXTRACT_ALL            = YES
EXTRACT_PRIVATE        = YES
EXTRACT_STATIC         = YES
EXTRACT_LOCAL_CLASSES  = YES
EXTRACT_LOCAL_METHODS  = YES
HIDE_UNDOC_RELATIONS   = NO
HIDE_UNDOC_MEMBERS     = NO

3. 类图生成专用配置

3.1 启用图表支持

HAVE_DOT               = YES

所有基于 Graphviz 的图表都以该选项为前提，未启用时其余图表配置均不生效。

3.2 类图类型

CLASS_DIAGRAMS         = YES    # 1.9.3 起废弃，功能由 CLASS_GRAPH 取代；1.8.x 有效
CLASS_GRAPH            = YES    # 继承关系图
COLLABORATION_GRAPH    = YES    # 协作关系图（实现依赖：继承、包含、成员引用）
TEMPLATE_RELATIONS     = YES    # 模板实例化关系

3.3 UML 外观

UML_LOOK               = YES    # 启用标准 UML 外观
UML_LIMIT_NUM_FIELDS   = 50     # 限制每个类显示的字段数量
DOT_UML_DETAILS        = YES    # 显示成员类型和参数详情（1.9.4 引入；1.8.x 无此选项，忽略此行）

3.4 图表规模与格式

DOT_GRAPH_MAX_NODES    = 100    # 单图最大节点数
MAX_DOT_GRAPH_DEPTH    = 0      # 图的最大深度（0 表示无限制）
DOT_IMAGE_FORMAT       = svg    # 输出格式（svg/png/jpg）
INTERACTIVE_SVG        = YES    # 启用 SVG 交互功能
DOT_TRANSPARENT        = YES    # 透明背景（1.9.2 起随暗色主题废弃，图片恒为透明背景；1.8.x 有效）
DOT_MULTI_TARGETS      = YES    # 单次运行输出多目标（1.9.5 起废弃；1.8.x 有效）

4. 输出格式配置

GENERATE_HTML          = YES    # 生成 HTML 文档
GENERATE_LATEX         = NO     # 不生成 LaTeX 文档
GENERATE_TREEVIEW      = YES    # 侧边树形导航（只接受 YES/NO，ALL 是早已移除的旧值）
HTML_DYNAMIC_SECTIONS  = YES    # 动态折叠/展开章节

SOURCE_BROWSER         = YES    # 源码浏览功能
INLINE_SOURCES         = NO     # 不内联源码

SEARCHENGINE           = YES    # 启用搜索功能
SERVER_BASED_SEARCH    = NO     # 客户端搜索

DOXYFILE_ENCODING      = UTF-8
OUTPUT_LANGUAGE        = Chinese

5. Windows 特殊配置

Windows 环境需要显式指定 Graphviz 路径：

DOT_PATH              = "C:/Program Files/Graphviz/bin"

注意：路径使用正斜杠 / 或双反斜杠 \\，并用引号包围包含空格的路径。

6. 生成与查看

doxygen -g          # 1. 生成默认配置文件
# 2. 编辑 Doxyfile，或替换为文末模板
doxygen Doxyfile    # 3. 生成文档

生成的文档位于 ./docs/html/，主入口是 index.html；类图在各类的文档页面中（"类图"和"协作图"部分）。

7. 关键配置速查

配置项	推荐值	作用
HAVE_DOT	YES	启用 Graphviz 支持，所有图表生成的基础
UML_LOOK	YES	使类图具有标准 UML 风格外观
CLASS_GRAPH	YES	生成类继承关系图
COLLABORATION_GRAPH	YES	生成类协作关系图（继承、包含、引用）
DOT_IMAGE_FORMAT	svg	生成矢量图，支持无损缩放
UML_LIMIT_NUM_FIELDS	50	控制类节点复杂度，防止图表过大

8. 版本兼容对照

旧教程与新版本 Doxygen 的不兼容主要集中在以下几个选项，配置前先核对版本：

选项	变化	生效版本
DOT_TRANSPARENT	废弃：暗色主题下图片恒为透明背景	1.9.2 起
CLASS_DIAGRAMS	废弃：由 HAVE_DOT + CLASS_GRAPH 取代	1.9.3 起
DOT_UML_DETAILS	新增：UML 图中显示成员类型与参数	1.9.4 起
DOT_MULTI_TARGETS	废弃	1.9.5 起
GENERATE_TREEVIEW	只接受 YES/NO	ALL 为早已移除的旧值

上述选项在 1.8.x 上仍然有效；在对应版本之后会触发 unknown tag 警告，删除相应行即可，不影响其余配置。

9. 大型项目的性能取舍

项目规模较大时，需要在图表完整性与生成速度之间权衡：

• 控制图表规模：降低 DOT_GRAPH_MAX_NODES（如设为 50）
• 限制图表深度：设置 MAX_DOT_GRAPH_DEPTH（如设为 3）
• 简化类节点：减小 UML_LIMIT_NUM_FIELDS（如设为 10-20）
• 选择合适格式：大型项目可考虑用 png 而非 svg，减少文件体积

10. 故障排查

类图未正确生成时，按以下顺序排查：

1. 工具：dot -V 能否正常执行；Doxygen 与 Graphviz 版本是否匹配
2. 路径：Windows 检查 DOT_PATH；确认 dot 在 PATH 中
3. 配置：HAVE_DOT = YES 是否启用；相关类图选项是否开启
4. 源码：类定义是否有访问修饰符（public/protected/private）；源文件是否被 INPUT 和 FILE_PATTERNS 覆盖
5. 日志：关注运行时的控制台警告，尤其是 Graphviz 相关错误与 unknown tag 提示

11. 完整配置模板

# Doxyfile - 类图生成配置（在 1.8.17 / Ubuntu 20.04 验证；1.9.x 差异见注释与第 8 节对照表）

# 项目设置
PROJECT_NAME           = "My Project"
PROJECT_BRIEF          = "使用 Doxygen 生成类图示例"
PROJECT_NUMBER         = 1.0
OUTPUT_DIRECTORY       = ./docs
CREATE_SUBDIRS         = YES

# 输入设置
INPUT                  = .
FILE_PATTERNS          = *.cpp *.h *.hpp *.cxx *.hxx *.cc *.hh
RECURSIVE              = YES
EXCLUDE_PATTERNS       = */test/* */build/* */cmake-build-*/*

# 提取设置
EXTRACT_ALL            = YES
EXTRACT_PRIVATE        = YES
EXTRACT_STATIC         = YES
EXTRACT_LOCAL_CLASSES  = YES
EXTRACT_LOCAL_METHODS  = YES
HIDE_UNDOC_RELATIONS   = NO
HIDE_UNDOC_MEMBERS     = NO
HIDE_IN_BODY_DOCS      = NO

# 图表生成（核心）
HAVE_DOT               = YES
CLASS_DIAGRAMS         = YES    # 1.9.3 起废弃；1.8.x 有效
CLASS_GRAPH            = YES
COLLABORATION_GRAPH    = YES
TEMPLATE_RELATIONS     = YES
UML_LOOK               = YES
UML_LIMIT_NUM_FIELDS   = 50
DOT_UML_DETAILS        = YES    # 1.9.4 引入；1.8.x 忽略

# 图表优化
DOT_GRAPH_MAX_NODES    = 100
MAX_DOT_GRAPH_DEPTH    = 0
DOT_IMAGE_FORMAT       = svg
INTERACTIVE_SVG        = YES
DOT_TRANSPARENT        = YES    # 1.9.2 起废弃；1.8.x 有效
DOT_MULTI_TARGETS      = YES    # 1.9.5 起废弃；1.8.x 有效

# 输出格式
GENERATE_HTML          = YES
GENERATE_LATEX         = NO
GENERATE_TREEVIEW      = YES
HTML_DYNAMIC_SECTIONS  = YES
SOURCE_BROWSER         = YES
INLINE_SOURCES         = NO

# 搜索与引用
SEARCHENGINE           = YES
SERVER_BASED_SEARCH    = NO
REFERENCES_LINK_SOURCE = YES

# 编码与语言
DOXYFILE_ENCODING      = UTF-8
OUTPUT_LANGUAGE        = Chinese

小结

类图生成的核心配置项：HAVE_DOT 启用 Graphviz 支持，CLASS_GRAPH 与 COLLABORATION_GRAPH 决定生成的图表类型，UML_LOOK 启用 UML 外观，DOT_UML_DETAILS 显示成员类型与参数（1.9.4 起）。其余配置用于调节图表规模与生成性能。参考旧教程配置时，先对照第 8 节的版本兼容表，可以避免多数配置不生效与废弃警告问题。