个人笔记

外观

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

1. 概述 ​

Doxygen 结合 Graphviz 工具能够为 C++ 项目自动生成专业的 UML 类图。该方案成本低、集成度高，是文档化 C++ 代码结构的常用方法。本文档详细说明从环境准备到类图生成的完整流程。

2. 环境准备 ​

2.1 必需工具 ​

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

2.2 安装方法 ​

Linux (Ubuntu/Debian)：

bash
sudo apt install doxygen graphviz

macOS (使用 Homebrew)：

bash
brew install doxygen graphviz

Windows：

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

2.3 验证安装 ​

执行以下命令验证工具是否正确安装：

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

3. 配置文件设置 ​

3.1 生成默认配置 ​

在项目根目录执行：

bash
doxygen -g

此命令生成名为 Doxyfile 的默认配置文件。

3.2 核心配置项详解 ​

3.2.1 基础项目配置 ​

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

3.2.2 源码扫描配置 ​

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

3.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

4. 类图生成专用配置 ​

4.1 图表支持启用 ​

HAVE_DOT               = YES

4.2 类图类型配置 ​

CLASS_DIAGRAMS         = YES    # 为有继承关系的类生成图
CLASS_GRAPH            = YES    # 继承关系图
COLLABORATION_GRAPH    = YES    # 协作关系图（使用关系）
TEMPLATE_RELATIONS     = YES    # 模板实例化关系

4.3 UML 外观设置 ​

UML_LOOK               = YES    # 启用标准 UML 外观
UML_LIMIT_NUM_FIELDS   = 50     # 限制每个类显示的字段数量
DOT_UML_DETAILS        = YES    # 在图中显示成员类型和参数详情

4.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     # 透明背景
DOT_MULTI_TARGETS      = YES     # 支持多目标输出

5. 输出格式配置 ​

GENERATE_HTML          = YES    # 生成 HTML 文档
GENERATE_LATEX         = NO     # 不生成 LaTeX 文档
GENERATE_TREEVIEW      = ALL    # 生成完整的树形导航
HTML_DYNAMIC_SECTIONS  = YES    # 动态折叠/展开章节

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

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

DOXYFILE_ENCODING      = UTF-8  # 配置文件编码
OUTPUT_LANGUAGE        = Chinese # 输出语言

6. Windows 系统特殊配置 ​

Windows 用户需要显式指定 Graphviz 路径：

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

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

7. 使用流程 ​

7.1 配置步骤 ​

bash
# 1. 生成默认配置文件
doxygen -g

# 2. 编辑 Doxyfile，应用所需配置
# （可直接替换为本文提供的完整配置）

# 3. 生成文档
doxygen Doxyfile

7.2 查看结果 ​

生成的文档位于 ./docs/html/ 目录：

  • 主入口：index.html
  • 类图位置：各类文档页面中的 "类图" 或 "协作图" 部分

8. 关键配置项说明 ​

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

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. 日志分析：

    • 运行 doxygen 时观察控制台输出的警告信息
    • 检查是否有 Graphviz 相关的错误提示

11. 完整配置文件模板 ​

bash
# Doxyfile 1.9.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
CLASS_GRAPH            = YES
COLLABORATION_GRAPH    = YES
TEMPLATE_RELATIONS     = YES
UML_LOOK               = YES
UML_LIMIT_NUM_FIELDS   = 50
DOT_UML_DETAILS        = YES

# 图表优化
DOT_GRAPH_MAX_NODES    = 100
MAX_DOT_GRAPH_DEPTH    = 0
DOT_IMAGE_FORMAT       = svg
INTERACTIVE_SVG        = YES
DOT_TRANSPARENT        = YES
DOT_MULTI_TARGETS      = YES

# 输出格式
GENERATE_HTML          = YES
GENERATE_LATEX         = NO
GENERATE_TREEVIEW      = ALL
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

此配置模板可根据具体项目需求进行调整，重点关注项目名称、输入路径、排除模式以及图表规模限制等参数。

基于 VitePress 构建

Copyright © 2026 ww1820