甘特图是项目管理可视化的基石。它将任务映射到时间线上，展示依赖关系、突出里程碑，并让资源分配对整个团队透明可见。传统上在 Microsoft Project 或 Excel 中制作，而现在甘特图可以完全用代码来创建——使其可版本控制、可自动化，并且易于嵌入文档中。
本指南将教你使用 Mermaid 构建专业甘特图所需的一切知识，从基础语法到高级项目规划模式。
为什么要用 Mermaid 画甘特图？
传统的甘特图工具将你的数据锁定在专有文件格式中。Mermaid 彻底改变了这一范式。
- 文本化源码：你的进度计划保存在 Git 中，支持 Pull Request 审查和变更追踪。
- 快速迭代：调整截止日期或添加任务只需几秒钟，无需在嵌套菜单中点击。
- 文档原生：直接将实时甘特图嵌入 README、Wiki 或技术规范中。
- CI/CD 兼容：从里程碑数据自动生成项目报告。
基础语法
每个甘特图都以 gantt 关键字开头，接着是日期格式声明和任务定义。
gantt
title 网站重构项目
dateFormat YYYY-MM-DD
section 设计阶段
线框图 :a1, 2025-12-01, 7d
视觉设计 :a2, after a1, 10d
section 开发阶段
前端开发 :a3, after a2, 14d
后端 API :a4, after a2, 10d
section 测试阶段
QA 测试 :a5, after a3, 7d
Bug 修复 :a6, after a5, 5d
关键组件说明
| 组件 | 语法 | 用途 |
|---|---|---|
title | title 项目名称 | 显示图表标题 |
dateFormat | dateFormat YYYY-MM-DD | 定义日期解析方式 |
section | section 阶段名称 | 将相关任务分组显示 |
| 任务名称 | 任务名称 | 图表上的人类可读标签 |
| 任务 ID | :id, | 可选标识符，用于依赖引用 |
| 开始日期 | 2025-12-01 或 after id | 任务开始时间 |
| 持续时间 | 7d, 2w, 1m | 任务运行时长 |
支持的日期格式
Mermaid 接受多种日期格式模式，选择与你数据源匹配的即可。
| 格式模式 | 示例 | 适用场景 |
|---|---|---|
YYYY-MM-DD | 2025-12-01 | ISO 标准，无歧义 |
MM-DD-YYYY | 12-01-2025 | 美式数据源 |
DD-MM-YYYY | 01-12-2025 | 欧洲数据源 |
YYYY/MM/DD | 2025/12/01 | 替代分隔符风格 |
始终在图表顶部用 dateFormat 声明你选择的格式。
任务依赖关系
依赖关系是甘特图发挥真正威力的地方。Mermaid 支持两种依赖类型。
使用 after 的顺序依赖
使用 after taskId 让某个任务在另一个任务完成后才开始。
gantt
dateFormat YYYY-MM-DD
调研 :r1, 2025-12-01, 5d
分析 :r2, after r1, 3d
撰写报告 :r3, after r2, 4d
多前置任务依赖
一个任务可以依赖多个前置任务，它会在最后一个依赖完成后才开始。
gantt
dateFormat YYYY-MM-DD
前端开发 :f1, 2025-12-01, 10d
后端开发 :b1, 2025-12-01, 8d
集成测试 :i1, after f1 b1, 5d
任务状态指示器
Mermaid 允许你用视觉状态标签标记任务。
| 状态 | 语法 | 视觉效果 |
|---|---|---|
| 进行中 | Active, taskId, ... | 粗体彩色条 |
| 已完成 | Done, taskId, ... | 条纹或浅色条 |
| 关键路径 | Crit, taskId, ... | 红色高亮条 |
gantt
dateFormat YYYY-MM-DD
section 冲刺 1
规划 :done, p1, 2025-12-01, 2d
核心功能 :active, c1, after p1, 5d
安全审计 :crit, s1, after c1, 3d
文档编写 :d1, after c1, 4d
里程碑
里程碑代表零持续时间的事件，如截止日期、发布节点或评审关口。
gantt
dateFormat YYYY-MM-DD
Alpha 开发 :a1, 2025-12-01, 14d
Alpha 发布 :milestone, am, after a1, 0d
Beta 开发 :b1, after am, 10d
Beta 发布 :milestone, bm, after b1, 0d
里程碑在时间线上渲染为菱形形状，使其作为检查点一目了然。
实战案例：产品发布
以下是一个典型的产品发布甘特图，跨越三个月。
gantt
title 2026 Q1 产品发布
dateFormat YYYY-MM-DD
section 策略
市场调研 :done, mr, 2026-01-05, 10d
竞品分析 :done, ca, after mr, 7d
发布策略 :active, ls, after ca, 5d
section 产品
功能冻结 :milestone, ff, 2026-01-28, 0d
QA 测试 :qa, 2026-01-29, 14d
Bug 修复冲刺 :bf, after qa, 7d
发布候选版 :milestone, rc, after bf, 0d
section 市场
内容创作 :cc, 2026-02-01, 14d
落地页开发 :lp, after cc, 7d
邮件营销 :ec, after lp, 5d
section 发布
新闻稿 :pr, 2026-02-24, 3d
社交媒体推广 :sm, after pr, 2d
正式发布 :milestone, ol, 2026-03-01, 0d
甘特图的最佳实践
遵循以下指南，让你的甘特图保持可读性和可维护性。
使用有意义的任务 ID。对于小型图表，r1、dev1 或 qa2 这样的 ID 已经足够。对于复杂项目，请使用描述性 ID，如 frontend_dev 或 security_audit。
使用 section 分组。分组创建视觉分隔。一个包含 20 个未分组任务的图表令人不知所措；同样的任务分成 4 个 section 后变得一目了然。
保持持续时间现实。Mermaid 不会验证你的进度计划是否可行。将其作为可视化层，覆盖在来自项目管理工具的现实估算之上。
与其他图表结合使用。将甘特图链接到包含流程图的需求文档，或开发阶段的 API 交互时序图。
导出给利益相关者。Mermaid2Img 让你可以将甘特图导出为 PNG 或 PDF，用于 PowerPoint 演示、邮件更新或打印报告。
常见陷阱
| 陷阱 | 解决方案 |
|---|---|
缺少 dateFormat | 在任何任务之前始终声明 dateFormat |
| 循环依赖 | 确保 after 引用不会形成闭环 |
| 任务 ID 重复 | 每个 ID 在图表内必须唯一 |
| 无效持续时间单位 | 使用 d 表示天，w 表示周，m 表示月，y 表示年 |
| 未声明的前置任务 | after 中引用的任务必须在依赖任务之前存在 |