1. 为什么我建议你在Typora里直接用Mermaid画甘特图作为一个常年和项目排期打交道的人我试过Excel手拉进度条、试过专门的甘特图软件、也试过在线协作工具里的各种图表模块。但最后真正让我稳定下来、几乎每天都要用的方案反而是Typora里用Mermaid语法写甘特图。原因很简单它把“写计划”和“画计划”合成了一件事所有内容都是纯文本改日期、调顺序、增删任务全部靠敲字完成不依赖鼠标拖拽也不会因为图表组件一升级就找不到按钮在哪。Typora本身是一款Markdown编辑器但它内置了Mermaid图表引擎甘特图就是Mermaid支持的图表类型之一。这意味着你只需要在Typora里新建一个代码块把语言标记成mermaid然后按照gantt语法写出任务、时间、依赖关系Typora就会实时渲染出一张完整的甘特图。更关键的是这个渲染是本地完成的不需要联网也不需要把数据上传到任何服务器。对于做项目管理的朋友来说这种“所见即所得、数据完全在自己手里”的体验确实比在线工具更踏实。那这个方案适合谁呢适合这么几类人平时用Markdown记笔记、写文档的开发者或产品经理不希望为了画一张甘特图再去学一个新软件需要把项目排期放进文档、Wiki、Git仓库里的团队希望图表随文档一起版本管理有轻量级任务管理需求但觉得专门的甘特图软件功能太重、学习成本太高的个人用户想快速给周报、月报、方案文档配上一张清晰时间轴图的职场人用Typora画图比在Excel里反复对齐格式快得多。当然Typora的甘特图并不是万能的。它没有Excel里那种精细到颜色渐变、工时汇总、资源冲突检测的功能也没有专业项目管理软件里的关键路径自动计算。但如果你要的是“把计划说明白”而不是“用软件管理整个项目”那这个组合几乎是最低成本的方案。后面我会把语法、实操、进阶技巧和踩坑经验都拆开讲清楚。2. 理解甘特图的核心要素从Excel思维切换到Mermaid思维很多人第一次用Mermaid画甘特图最容易犯的错就是拿Excel的思维去套——在Excel里你要先排好一行一行的任务再设置开始日期和持续天数最后手动把条形图拉出来。而Mermaid的gantt图本质上是一种声明式描述你只管告诉它“有什么任务、从哪天开始、持续多久、依赖谁”它自动帮你计算时间轴并渲染成图。这个思维转换是关键。2.1 甘特图右侧进度条时间设置的本质热搜词里有“甘特图右边进度条时间设置”这个说法其实指的就是甘特图中每一条任务横条所处的日期范围。在Excel里你可能会手动调整条形图的位置来对齐日期在Mermaid里位置的确定靠的是两个信息任务的开始日期或依赖关系和任务持续时间。Mermaid会根据你定义的时间单位自动排布横条右侧那条主轴就是整体时间线所有任务条都按日期映射到这条轴上。理解这一点后你会发现所谓的“时间设置”其实就是在写任务时把开始时间和时长写对。比如你写了一个任务开始时间是2025-06-01持续5天那它的进度条就会落在6月1日到6月5日之间。如果你前面有依赖任务你还可以用after语法让它自动紧跟前面任务的结束时间这样改前面的日期后面所有任务的时间轴都会自动跟着平移这是Excel里最难做到、而Mermaid里最爽的功能之一。2.2 Mermaid甘特图的基本语法结构Mermaid的gantt图核心语法非常简洁一个典型的代码块长这样mermaid gantt title 项目开发排期 dateFormat YYYY-MM-DD section 需求阶段 需求调研 :a1, 2025-06-01, 5d 需求评审 :a2, after a1, 2d section 开发阶段 前端开发 :b1, after a2, 10d 后端开发 :b2, after a2, 12d逐个拆开看 - 第一行gantt表示声明这是一个甘特图 - title后面跟着的是图表标题可选 - dateFormat用于指定输入日期字符串的格式YYYY-MM-DD是最常用的如果你习惯用2025/06/01这种写法就在这里改成YYYY/MM/DD注意大小写敏感 - section用来把任务分组成不同的区域比如“需求阶段”“开发阶段”每个section下的任务都会在图表左侧显示为一个分组标题 - 每个任务行由“任务名称: 任务标识符, 时间定义”构成任务标识符可选但建议写尤其在需要声明依赖关系时非常重要 - 时间定义可以是“具体日期持续时长”比如2025-06-01, 5d也可以是“after 某个任务标识符”这种依赖式写法。 这里值得多说一句任务标识符比如上面的a1、b1不写也可以但一旦你的任务之间需要表达先后关系就必须给前置任务起一个名字然后在后置任务里用after 名字来引用。很多人刚上手时会跳过标识符结果后面想加依赖就傻眼了还得回头给每个任务补名字。我个人的习惯是只要是多个任务一律先把标识符写上哪怕是a1、a2这种毫无语义的编号也比没有好。 ## 3. 从入门到实战一个完整项目甘特图的绘制全过程 我觉得最好的学习方式不是背语法而是跟着一个完整案例走一遍。下面我用一个模拟的“公司官网改版项目”来演示从零开始把需求、设计、开发、测试、上线整个周期画成一张甘特图。这个过程里我会故意加入依赖关系、里程碑、关键任务标记、状态标记等元素顺便把常见的坑一起带出来。 ### 3.1 明确项目阶段和任务拆解 画甘特图之前先别急着写代码先用纸笔或者在文档里列清楚你的任务清单。这是很多人偷懒跳过的步骤但恰恰是最重要的一步。你至少要明确每一阶段的名称、每个任务的名称、大概的开始时间、持续时间以及任务之间的先后依赖。 以官网改版为例我先把任务拆成五个阶段 | 阶段 | 任务 | 预计开始 | 预计时长 | |------|------|----------|----------| | 需求阶段 | 需求调研 | 2025-06-01 | 5天 | | 需求阶段 | 需求评审 | 2025-06-08 | 2天 | | 设计阶段 | UI设计 | 2025-06-10 | 7天 | | 开发阶段 | 前端开发 | 2025-06-17 | 10天 | | 开发阶段 | 后端开发 | 2025-06-20 | 8天 | | 测试阶段 | 功能测试 | 2025-06-27 | 5天 | | 测试阶段 | 修复与回归 | 2025-07-02 | 4天 | | 上线阶段 | 部署上线 | 2025-07-06 | 1天 | 这个表看着挺简单但你能感受到一些细节问题需求评审是6月8日开始但需求调研6月1日开始持续5天6月5日就结束了中间6月6日到6月7日是周末这里先不考虑非工作日的处理后面我会专门讲如何让周末不显示在时间轴上。UI设计在需求评审之后开始但评审持续2天到6月9日按理设计应该在6月10日开始这个规划是合理的。前后端开发几乎并行前端从6月17日开始后端从6月20日开始这说明两者没有严格的先后关系但后端稍晚这种并行关系在甘特图里就是两条独立的横条时间上部分重叠。 ### 3.2 用Mermaid语法一步步实现 把上面的表转成Mermaid语法第一步先写最基础的版本不加入依赖关系直接给每个任务指定日期和时长 markdown mermaid gantt title 公司官网改版项目排期 dateFormat YYYY-MM-DD section 需求阶段 需求调研 :a1, 2025-06-01, 5d 需求评审 :a2, 2025-06-08, 2d section 设计阶段 UI设计 :b1, 2025-06-10, 7d section 开发阶段 前端开发 :c1, 2025-06-17, 10d 后端开发 :c2, 2025-06-20, 8d section 测试阶段 功能测试 :d1, 2025-06-27, 5d 修复与回归 :d2, 2025-07-02, 4d section 上线阶段 部署上线 :e1, 2025-07-06, 1d此时渲染出来的图已经有了完整的分组、日期轴和任务横条但任务之间是孤立的看不出谁依赖谁。而且如果你后续改了需求评审的时间UI设计的时间不会自动跟着变这就是缺少依赖关系的问题。 接下来我改进一下把明显的依赖关系写进去。需求评审依赖需求调研完成UI设计依赖需求评审完成前端开发依赖UI设计完成功能测试依赖前端和后端都完成修复和回归依赖功能测试部署上线依赖修复完成。修正后的代码 markdown mermaid gantt title 公司官网改版项目排期依赖版 dateFormat YYYY-MM-DD section 需求阶段 需求调研 :a1, 2025-06-01, 5d 需求评审 :a2, after a1, 2d section 设计阶段 UI设计 :b1, after a2, 7d section 开发阶段 前端开发 :c1, after b1, 10d 后端开发 :c2, after b1, 8d section 测试阶段 功能测试 :d1, after c1 c2, 5d 修复与回归 :d2, after d1, 4d section 上线阶段 部署上线 :e1, after d2, 1d注意一个很关键的细节功能测试任务的前置依赖有两个分别是c1和c2你需要在after后面用空格分隔多个标识符写成after c1 c2。这个语法我第一次用的时候就卡住了以为要写成after c1, after c2或者after [c1, c2]结果渲染直接报错。实际语法就是空格分隔不需要逗号。 这样改进之后整个图的逻辑链就清晰了每一个任务的横条都会根据前置任务的结束位置来自动往后排你只要改需求调研的日期后面所有任务的时间轴都会自动重新计算。这就是依赖式写法的最大价值。 ### 3.3 加入里程碑、关键任务标记和状态颜色 基础的依赖版已经能用了但如果你的项目里有关键节点比如评审通过、联调完成、上线发布这类节点甘特图里可以用里程碑来表达。里程碑在Mermaid的gantt里本质是一种持续时间为0的任务显示为菱形符号。写法如下 markdown mermaid gantt title 公司官网改版项目排期里程碑版 dateFormat YYYY-MM-DD section 需求阶段 需求调研 :a1, 2025-06-01, 5d 需求评审 :a2, after a1, 2d 需求评审通过 :milestone, m1, after a2, 0d section 设计阶段 UI设计 :b1, after a2, 7d UI设计定稿 :milestone, m2, after b1, 0d section 开发阶段 前端开发 :c1, after b1, 10d 后端开发 :c2, after b1, 8d 前后端联调完成 :milestone, m3, after c1 c2, 0d section 测试阶段 功能测试 :d1, after c1 c2, 5d 修复与回归 :d2, after d1, 4d section 上线阶段 部署上线 :e1, after d2, 1d 上线完成 :milestone, m4, after e1, 0d里程碑的任务定义里用了milestone关键字表示这是一个里程碑然后给它一个标识符再写after依赖和0d时长。渲染后你会看到在对应的时间点出现一个菱形标记比普通任务横条更醒目。 如果项目里存在关键任务想要在图中突出显示可以在任务定义里加上crit关键字。比如前端开发是整个项目链路里路径最长的关键路径可以写成 markdown 前端开发 :crit, c1, after b1, 10d加了crit之后这个任务在渲染出来的图上会有特殊的红色样式具体颜色取决于Mermaid默认皮肤一眼就能看出它是影响整体进度的关键环节。另外任务还可以标记状态比如active表示进行中、done表示已完成。比如需求调研已经完成、UI设计正在进行需求调研 :done, a1, 2025-06-01, 5d 需求评审 :done, a2, after a1, 2d UI设计 :active, b1, after a2, 7d注意状态关键字是有顺序的但Mermaid对顺序比较宽容比如done, a1和a1, done都能识别。不过为了统一和可读性我建议固定用“状态, 标识符, 时间定义”的顺序这样团队协作时其他人读起来也顺畅。上面这些要素加在一起一张信息完整的项目甘特图就成型了。这里有一段完整的成品代码你可以直接复制到Typora里看效果mermaid gantt title 公司官网改版项目完整排期 dateFormat YYYY-MM-DD section 需求阶段 需求调研 :done, a1, 2025-06-01, 5d 需求评审 :done, a2, after a1, 2d 需求评审通过 :milestone, m1, after a2, 0d section 设计阶段 UI设计 :active, b1, after a2, 7d UI设计定稿 :milestone, m2, after b1, 0d section 开发阶段 前端开发 :crit, c1, after b1, 10d 后端开发 :c2, after b1, 8d 前后端联调完成 :milestone, m3, after c1 c2, 0d section 测试阶段 功能测试 :d1, after c1 c2, 5d 修复与回归 :d2, after d1, 4d section 上线阶段 部署上线 :e1, after d2, 1d 上线完成 :milestone, m4, after e1, 0d### 3.4 工作日与周末的隐藏问题 这是很多刚开始用Mermaid画甘特图的人会遇到的一个细节问题默认情况下日期轴会把周六周日也显示出来而且默认日期轴不是周一开头而是周日开头。比如我前面举例子的项目从6月1日开始6月1日正好是周日渲染出来你会发现时间轴的起点是周日。这在看中文项目的排期时多少有点别扭因为国内团队大多习惯周一作为一周的开始。 要解决这个问题可以在标题和dateFormat后面加上excludes参数 markdown gantt title 工作日排期示例 dateFormat YYYY-MM-DD excludes weekends加了excludes weekends之后周六日会自动从时间轴上剔除任务横条会跳过周末连续的工作日才会排在一起。比如一个从周五开始持续3天的任务渲染出来会显示为周五、下周一、下周二中间周六日不会出现断档。这个参数对项目排期特别实用因为实际工作中绝大多数任务都不应该把周末算进去否则按自然日排期经常会出现“明明预留了5天结果里面有两天是周末”的尴尬情况。除了weekends你还可以指定具体的排除日期比如法定节假日excludes 2025-10-01, 2025-10-02, 2025-10-03注意多个日期之间用英文逗号加空格分隔。我自己做项目排期时通常先写excludes weekends再根据实际公司日历补上节假日。4. 进阶技巧让甘特图真正好用的几个核心配置基础语法掌握了以后你可能会发现渲染出来的图在样式上总有些不满意的点比如时间轴格式不好看、任务描述太长被截断、图上没有显示半成品所需的“进度”细条等。这一部分我把自己实测过的一些实用技巧整理出来每个都配了说明。4.1 自定义时间轴格式Mermaid甘特图默认的时间轴显示格式是类似“2025-06-01”这样的完整日期在某些场景下显得太长。你可以用axisFormat参数来调整时间轴的显示方式。这个参数支持d3时间格式化语法比如你想让日期显示成“6/1”这种短格式gantt title 时间轴格式优化示例 dateFormat YYYY-MM-DD axisFormat %m/%d%m表示两位月份%d表示两位日期。如果你想显示成“2025-06”这种年月的格式就写axisFormat %Y-%m。这看起来是个小功能但在文档里展示时很实用。特别是当你把一个长时间跨度的项目比如6个月放进文档时完整日期会挤在一起换成“第几周”或者“年月”格式会清爽很多。4.2 任务进度和状态标记除了done和active你还可以用类似“50%”这样的进度百分比来标记任务完成度。比如UI设计已经完成了六成可以写成UI设计 :b1, after a2, 7d, 50%渲染后这个任务的横条内部会有一段灰色填充表示完成度。这个功能在做周报、月报、项目进展同步时特别有用。我通常会在每周五把当前所有任务的进度百分比更新一遍然后截图贴在周报里领导和同事一眼就能看出哪些任务滞后了、哪些正常推进。注意进度百分比是跟在持续时长后面用空格分隔。如果你的任务没有指定日期而是用了after依赖同样可以加进度标记。4.3 设置任务标签和样式快捷方式有时候你需要在图上看一些补充信息比如任务负责人、优先级等。Mermaid甘特图本身没有专门的字段但你可以把这类信息拼在任务名称后面用冒号分隔比如前端开发 - 张三 :crit, c1, after b1, 10d这样渲染出来左侧的任务列表就会显示“前端开发 - 张三”虽然不够结构化但胜在简单直接。如果你不想在图上显示这些备注也可以在任务名称里只保留任务名把负责人信息写在代码注释里——Mermaid语法本身支持以%%开头的注释行。4.4 多项目叠加和子任务拆分技巧如果你的需求是要在同一个图上展示两个子项目比如“官网改版”和“CRM系统升级”可以用section来做第一层分组然后在每个section内部用连续的任务名称模拟二级结构。比如gantt title 多项目并行排期 dateFormat YYYY-MM-DD excludes weekends section 官网改版 需求调研 :oa1, 2025-06-01, 5d 前端开发 :oc1, after oa1, 10d section CRM升级 需求梳理 :ca1, 2025-06-02, 3d 后端开发 :cc1, after ca1, 8d这里的关键是不同项目的任务标识符要避免重名。我见过有人把两个section里的任务都叫a1结果依赖关系乱掉的情况。所以跨section时即使Mermaid允许重名最好还是用不同的前缀比如o代表官网、c代表CRM来区分这样可以避免很多不必要的排查成本。4.5 在Excel思维和Mermaid思维之间找到结合点回到热搜词里的“甘特图excel制作教程”。如果你想用Excel做一张复杂的甘特图你需要在单元格里手动画色块、设置条件格式、调整坐标轴过程繁琐且改一次日期就要重来。而用Mermaid在Typora里画甘特图你只需要维护一份类似CSV的任务清单文本然后让图表自动渲染出来。两者本质上都是表达“任务-时间-依赖”这三个维度但Mermaid把表达成本降低了一个量级。如果你团队里已经有用Excel管理任务的习惯你可以引导他们先从Excel表格里把任务清单整理出来列清楚任务名、开始日期、持续天数、前置任务这四列然后一次性翻译成Mermaid语法。这样既能保留Excel在数据统计上的优势又能享受Typora甘特图在可视化上的便利。我在实际工作中已经把“Excel任务清单”作为团队日常维护的源文件把“Typora甘特图”作为每周向管理层汇报的展示成果两者各司其职效率提升非常明显。5. 高频报错与疑难排查我踩过的坑都在这里工具用得越深遇到问题就越多。Mermaid甘特图虽然语法简单但在Typora里实际使用时还是有一些典型问题尤其是渲染报错、日期不显示等。我把这些问题和排查思路整理成了一个速查表方便你直接对照处理。现象可能原因解决办法渲染后提示“Syntax error in text”语法写错比如标点用了中文逗号、引号不匹配检查任务定义里的冒号、逗号是否为英文半角尤其注意复制内容时中文标点混入甘特图完全不显示只有代码代码块语言写成非mermaid或者mermaid语法解析失败确认代码块第一行是mermaid注意不要写成markdown或gantt等任务横条重叠在一起任务之间没有写依赖且开始日期相同为任务增加after依赖或手动错开开始日期时间轴显示为一天但任务横条很长dateFormat与实际输入日期格式不匹配比如dateFormat写了YYYY-MM-DD但输入写成2025/06/01解析会出错周六日出现在时间轴上且排期混乱没有配置excludes weekends在gantt参数里加excludes weekends里程碑显示为普通任务横条里程碑时长写成了非0d确认里程碑时长写0d且加上milestone关键字修改了任务名但图上显示的还是旧名字Typora缓存未刷新或渲染器异常切换一下Typora的源码模式和实时预览模式或者重启Typora中文任务名显示乱码或截断字体或宽度限制导致通常重开文档即可恢复如果持续发生检查系统字体设置5.1 日期格式排查为什么我写的日期不生效这个问题值得单独拿出来讲因为它是很多人第一次画甘特图时最容易碰到的。dateFormat和输入日期必须严格匹配Mermaid支持的日期格式标记主要有YYYY四位年、YY两位年、MM两位月、DD两位日。如果你的dateFormat写的是YYYY-MM-DD那么任务日期就必须写成2025-06-01这种形式如果你写成2025/06/01Mermaid解析时会直接报错。反之如果你用的是斜杠格式dateFormat也要写YYYY/MM/DD。看似是个小细节但一旦日期格式不匹配整个图都可能渲染不出来而不是简单显示某个任务缺失。5.2 进度百分比不显示的原因有些人在任务定义里加了百分比但图上没反应。这通常是因为百分比写错了位置。比如写成任务A :50%, a1, 2025-06-01, 5d这是不对的。百分比应该放在持续时长后面正确写法是任务A :a1, 2025-06-01, 5d, 50%另外百分比必须是合法的数字百分比30%或50%都可以但写成abc%或150%这种就会解析失败或显示异常。注意百分比是和任务状态标记done、active共存的你可以写成:done, a1, 2025-06-01, 5d, 100%表示这个任务100%完成。5.3 Mermaid版本与Typora升级关于热搜词里提到的“typora mermaid怎么升级”这个其实要看Typora版本和Mermaid引擎的集成方式。Typora在安装包内部打入了特定版本的Mermaid库用户层面没有提供单独升级Mermaid引擎的开关。如果你想要新版的Mermaid功能最稳妥的方式是升级Typora本体官方更新日志里通常会注明Mermaid引擎的版本变化。如果你在Typora里遇到某个Mermaid新语法无法识别但同一段代码在Mermaid的官网在线编辑器里却能正常渲染那基本就是Typora内置引擎版本偏旧。这种情况要么等待Typora更新要么在另一个支持较新Mermaid的编辑器里完成图表渲染再把生成的图片贴回文档。5.4 Typora闪退与文档崩溃的预防Typora整体很稳定但在处理特别长的文档、特别复杂的Mermaid图时偶尔也会有卡顿甚至闪退的情况。我自己遇到过一次还是一个包含大量任务和中文描述的甘特图在连续编辑十几分钟后Typora突然闪退。后来排查发现主要是Typora在实时预览模式下每敲一个字符都会触发Mermaid重渲染图表太复杂时内存占用骤增。降低风险的办法有三条一是把代码块的编辑拆成小段写写一段渲染一段而不是一次性粘贴几百行二是在编辑复杂图表的代码块时临时切到源码模式等代码写完再切回预览模式三是及时保存文档Typora有自动恢复机制但别把希望完全寄托在自动恢复上。5.5 公式靠左与文档排版无关但很常用热搜词里有一条“typora 公式怎么靠左”这个虽然和甘特图本身无关但是说明很多人都是在Typora里同时处理正文、公式和图表。如果你想在Typora里让公式靠左而不是居中可以在公式块后加一个特殊标记或者把公式放在行内语法中。具体到行内公式用单个美元符号包裹它天然是跟随文本方向的。块级公式默认居中想强制靠左我试过在公式块末尾加\hfill之类的LaTeX命令部分版本有效但有些版本不生效。如果不是特别频繁需要靠左公式更实用的做法是把公式段落改成普通文本并居中前的自定义样式。这个话题和甘特图扯得有点远但既然很多人搜说明大家习惯把这类问题归到一起我顺便说一句Typora的排版逻辑里很多显示问题都要优先去检查“段落内换行符”和“前后空格”而不是去折腾模板样式。5.6 使用快捷键提高甘特图编辑效率最后分享一个我自己的操作习惯在Typora里写Mermaid代码块时不要每写完一行就切到预览模式看效果这样会频繁打断思路。我建议先一口气把任务描述写完然后用快捷键CtrlShiftKMac上是CmdShiftK快速插入代码块再按CtrlShift逗号或点击右下角的“/”图标切到源码模式编辑写完后切回预览。实际上Typora对代码块的支持很灵活你甚至可以先写一段普通的Markdown列表来列任务等任务清单确定后再转换成Mermaid代码块。这个流程可以让“思考任务结构”和“调试图表效果”两件事彼此分离效率会高很多。我在实际使用中还发现给甘特图的任务名称加上编号比如“1.需求调研”“2.需求评审”比在section里反复嵌套分组更直观尤其当任务数量超过20个的时候。因为Mermaid甘特图的section层级只有一层没有二级三级结构如果你试图用缩进或嵌套来表示层级渲染器会直接忽略。所以简单粗暴的编号法反而是最实用的层级表达方式。6. 总结一下这个方案在我工作流里的真实定位有人可能会问既然Typora的甘特图功能不如专业项目管理软件完整为什么还要推荐我的答案很简单因为它足够轻、足够快、足够透明。轻是指学习成本低一个下午就能完全上手快是指从想法到成图几乎零延迟不用切软件、不用手动排版透明是指所有数据都是纯文本放进Git仓库可以做版本对比换电脑或者换人接手都能无缝衔接。在我实际的工作流里Typora甘特图承担的是“方案沟通”和“进度汇报”这两个角色而不是“任务跟踪”和“资源管理”。做方案时我快速画一张图给团队对齐排期做汇报时我用同一张图更新进度状态截个图放进周报。真正执行层面的每日任务管理我依然会用专门的任务管理工具。这种“各司其职”的分工方式避免了被单一工具绑架的问题也让我在“快”和“重”之间找到了最舒服的平衡点。如果你也想在Typora里尝试甘特图我的建议是从今天手头的一个小项目开始哪怕只有三五个任务先画出来感受一下依赖关系带来的自动排期体验再逐步加入里程碑、关键路径、进度百分比这些进阶要素。用不了几天你大概率会和我一样再也不愿意回Excel里手动拖色块了。 Typora中使用Mermaid绘制甘特图：语法、依赖与常见问题
1. 为什么我建议你在Typora里直接用Mermaid画甘特图作为一个常年和项目排期打交道的人我试过Excel手拉进度条、试过专门的甘特图软件、也试过在线协作工具里的各种图表模块。但最后真正让我稳定下来、几乎每天都要用的方案反而是Typora里用Mermaid语法写甘特图。原因很简单它把“写计划”和“画计划”合成了一件事所有内容都是纯文本改日期、调顺序、增删任务全部靠敲字完成不依赖鼠标拖拽也不会因为图表组件一升级就找不到按钮在哪。Typora本身是一款Markdown编辑器但它内置了Mermaid图表引擎甘特图就是Mermaid支持的图表类型之一。这意味着你只需要在Typora里新建一个代码块把语言标记成mermaid然后按照gantt语法写出任务、时间、依赖关系Typora就会实时渲染出一张完整的甘特图。更关键的是这个渲染是本地完成的不需要联网也不需要把数据上传到任何服务器。对于做项目管理的朋友来说这种“所见即所得、数据完全在自己手里”的体验确实比在线工具更踏实。那这个方案适合谁呢适合这么几类人平时用Markdown记笔记、写文档的开发者或产品经理不希望为了画一张甘特图再去学一个新软件需要把项目排期放进文档、Wiki、Git仓库里的团队希望图表随文档一起版本管理有轻量级任务管理需求但觉得专门的甘特图软件功能太重、学习成本太高的个人用户想快速给周报、月报、方案文档配上一张清晰时间轴图的职场人用Typora画图比在Excel里反复对齐格式快得多。当然Typora的甘特图并不是万能的。它没有Excel里那种精细到颜色渐变、工时汇总、资源冲突检测的功能也没有专业项目管理软件里的关键路径自动计算。但如果你要的是“把计划说明白”而不是“用软件管理整个项目”那这个组合几乎是最低成本的方案。后面我会把语法、实操、进阶技巧和踩坑经验都拆开讲清楚。2. 理解甘特图的核心要素从Excel思维切换到Mermaid思维很多人第一次用Mermaid画甘特图最容易犯的错就是拿Excel的思维去套——在Excel里你要先排好一行一行的任务再设置开始日期和持续天数最后手动把条形图拉出来。而Mermaid的gantt图本质上是一种声明式描述你只管告诉它“有什么任务、从哪天开始、持续多久、依赖谁”它自动帮你计算时间轴并渲染成图。这个思维转换是关键。2.1 甘特图右侧进度条时间设置的本质热搜词里有“甘特图右边进度条时间设置”这个说法其实指的就是甘特图中每一条任务横条所处的日期范围。在Excel里你可能会手动调整条形图的位置来对齐日期在Mermaid里位置的确定靠的是两个信息任务的开始日期或依赖关系和任务持续时间。Mermaid会根据你定义的时间单位自动排布横条右侧那条主轴就是整体时间线所有任务条都按日期映射到这条轴上。理解这一点后你会发现所谓的“时间设置”其实就是在写任务时把开始时间和时长写对。比如你写了一个任务开始时间是2025-06-01持续5天那它的进度条就会落在6月1日到6月5日之间。如果你前面有依赖任务你还可以用after语法让它自动紧跟前面任务的结束时间这样改前面的日期后面所有任务的时间轴都会自动跟着平移这是Excel里最难做到、而Mermaid里最爽的功能之一。2.2 Mermaid甘特图的基本语法结构Mermaid的gantt图核心语法非常简洁一个典型的代码块长这样mermaid gantt title 项目开发排期 dateFormat YYYY-MM-DD section 需求阶段 需求调研 :a1, 2025-06-01, 5d 需求评审 :a2, after a1, 2d section 开发阶段 前端开发 :b1, after a2, 10d 后端开发 :b2, after a2, 12d逐个拆开看 - 第一行gantt表示声明这是一个甘特图 - title后面跟着的是图表标题可选 - dateFormat用于指定输入日期字符串的格式YYYY-MM-DD是最常用的如果你习惯用2025/06/01这种写法就在这里改成YYYY/MM/DD注意大小写敏感 - section用来把任务分组成不同的区域比如“需求阶段”“开发阶段”每个section下的任务都会在图表左侧显示为一个分组标题 - 每个任务行由“任务名称: 任务标识符, 时间定义”构成任务标识符可选但建议写尤其在需要声明依赖关系时非常重要 - 时间定义可以是“具体日期持续时长”比如2025-06-01, 5d也可以是“after 某个任务标识符”这种依赖式写法。 这里值得多说一句任务标识符比如上面的a1、b1不写也可以但一旦你的任务之间需要表达先后关系就必须给前置任务起一个名字然后在后置任务里用after 名字来引用。很多人刚上手时会跳过标识符结果后面想加依赖就傻眼了还得回头给每个任务补名字。我个人的习惯是只要是多个任务一律先把标识符写上哪怕是a1、a2这种毫无语义的编号也比没有好。 ## 3. 从入门到实战一个完整项目甘特图的绘制全过程 我觉得最好的学习方式不是背语法而是跟着一个完整案例走一遍。下面我用一个模拟的“公司官网改版项目”来演示从零开始把需求、设计、开发、测试、上线整个周期画成一张甘特图。这个过程里我会故意加入依赖关系、里程碑、关键任务标记、状态标记等元素顺便把常见的坑一起带出来。 ### 3.1 明确项目阶段和任务拆解 画甘特图之前先别急着写代码先用纸笔或者在文档里列清楚你的任务清单。这是很多人偷懒跳过的步骤但恰恰是最重要的一步。你至少要明确每一阶段的名称、每个任务的名称、大概的开始时间、持续时间以及任务之间的先后依赖。 以官网改版为例我先把任务拆成五个阶段 | 阶段 | 任务 | 预计开始 | 预计时长 | |------|------|----------|----------| | 需求阶段 | 需求调研 | 2025-06-01 | 5天 | | 需求阶段 | 需求评审 | 2025-06-08 | 2天 | | 设计阶段 | UI设计 | 2025-06-10 | 7天 | | 开发阶段 | 前端开发 | 2025-06-17 | 10天 | | 开发阶段 | 后端开发 | 2025-06-20 | 8天 | | 测试阶段 | 功能测试 | 2025-06-27 | 5天 | | 测试阶段 | 修复与回归 | 2025-07-02 | 4天 | | 上线阶段 | 部署上线 | 2025-07-06 | 1天 | 这个表看着挺简单但你能感受到一些细节问题需求评审是6月8日开始但需求调研6月1日开始持续5天6月5日就结束了中间6月6日到6月7日是周末这里先不考虑非工作日的处理后面我会专门讲如何让周末不显示在时间轴上。UI设计在需求评审之后开始但评审持续2天到6月9日按理设计应该在6月10日开始这个规划是合理的。前后端开发几乎并行前端从6月17日开始后端从6月20日开始这说明两者没有严格的先后关系但后端稍晚这种并行关系在甘特图里就是两条独立的横条时间上部分重叠。 ### 3.2 用Mermaid语法一步步实现 把上面的表转成Mermaid语法第一步先写最基础的版本不加入依赖关系直接给每个任务指定日期和时长 markdown mermaid gantt title 公司官网改版项目排期 dateFormat YYYY-MM-DD section 需求阶段 需求调研 :a1, 2025-06-01, 5d 需求评审 :a2, 2025-06-08, 2d section 设计阶段 UI设计 :b1, 2025-06-10, 7d section 开发阶段 前端开发 :c1, 2025-06-17, 10d 后端开发 :c2, 2025-06-20, 8d section 测试阶段 功能测试 :d1, 2025-06-27, 5d 修复与回归 :d2, 2025-07-02, 4d section 上线阶段 部署上线 :e1, 2025-07-06, 1d此时渲染出来的图已经有了完整的分组、日期轴和任务横条但任务之间是孤立的看不出谁依赖谁。而且如果你后续改了需求评审的时间UI设计的时间不会自动跟着变这就是缺少依赖关系的问题。 接下来我改进一下把明显的依赖关系写进去。需求评审依赖需求调研完成UI设计依赖需求评审完成前端开发依赖UI设计完成功能测试依赖前端和后端都完成修复和回归依赖功能测试部署上线依赖修复完成。修正后的代码 markdown mermaid gantt title 公司官网改版项目排期依赖版 dateFormat YYYY-MM-DD section 需求阶段 需求调研 :a1, 2025-06-01, 5d 需求评审 :a2, after a1, 2d section 设计阶段 UI设计 :b1, after a2, 7d section 开发阶段 前端开发 :c1, after b1, 10d 后端开发 :c2, after b1, 8d section 测试阶段 功能测试 :d1, after c1 c2, 5d 修复与回归 :d2, after d1, 4d section 上线阶段 部署上线 :e1, after d2, 1d注意一个很关键的细节功能测试任务的前置依赖有两个分别是c1和c2你需要在after后面用空格分隔多个标识符写成after c1 c2。这个语法我第一次用的时候就卡住了以为要写成after c1, after c2或者after [c1, c2]结果渲染直接报错。实际语法就是空格分隔不需要逗号。 这样改进之后整个图的逻辑链就清晰了每一个任务的横条都会根据前置任务的结束位置来自动往后排你只要改需求调研的日期后面所有任务的时间轴都会自动重新计算。这就是依赖式写法的最大价值。 ### 3.3 加入里程碑、关键任务标记和状态颜色 基础的依赖版已经能用了但如果你的项目里有关键节点比如评审通过、联调完成、上线发布这类节点甘特图里可以用里程碑来表达。里程碑在Mermaid的gantt里本质是一种持续时间为0的任务显示为菱形符号。写法如下 markdown mermaid gantt title 公司官网改版项目排期里程碑版 dateFormat YYYY-MM-DD section 需求阶段 需求调研 :a1, 2025-06-01, 5d 需求评审 :a2, after a1, 2d 需求评审通过 :milestone, m1, after a2, 0d section 设计阶段 UI设计 :b1, after a2, 7d UI设计定稿 :milestone, m2, after b1, 0d section 开发阶段 前端开发 :c1, after b1, 10d 后端开发 :c2, after b1, 8d 前后端联调完成 :milestone, m3, after c1 c2, 0d section 测试阶段 功能测试 :d1, after c1 c2, 5d 修复与回归 :d2, after d1, 4d section 上线阶段 部署上线 :e1, after d2, 1d 上线完成 :milestone, m4, after e1, 0d里程碑的任务定义里用了milestone关键字表示这是一个里程碑然后给它一个标识符再写after依赖和0d时长。渲染后你会看到在对应的时间点出现一个菱形标记比普通任务横条更醒目。 如果项目里存在关键任务想要在图中突出显示可以在任务定义里加上crit关键字。比如前端开发是整个项目链路里路径最长的关键路径可以写成 markdown 前端开发 :crit, c1, after b1, 10d加了crit之后这个任务在渲染出来的图上会有特殊的红色样式具体颜色取决于Mermaid默认皮肤一眼就能看出它是影响整体进度的关键环节。另外任务还可以标记状态比如active表示进行中、done表示已完成。比如需求调研已经完成、UI设计正在进行需求调研 :done, a1, 2025-06-01, 5d 需求评审 :done, a2, after a1, 2d UI设计 :active, b1, after a2, 7d注意状态关键字是有顺序的但Mermaid对顺序比较宽容比如done, a1和a1, done都能识别。不过为了统一和可读性我建议固定用“状态, 标识符, 时间定义”的顺序这样团队协作时其他人读起来也顺畅。上面这些要素加在一起一张信息完整的项目甘特图就成型了。这里有一段完整的成品代码你可以直接复制到Typora里看效果mermaid gantt title 公司官网改版项目完整排期 dateFormat YYYY-MM-DD section 需求阶段 需求调研 :done, a1, 2025-06-01, 5d 需求评审 :done, a2, after a1, 2d 需求评审通过 :milestone, m1, after a2, 0d section 设计阶段 UI设计 :active, b1, after a2, 7d UI设计定稿 :milestone, m2, after b1, 0d section 开发阶段 前端开发 :crit, c1, after b1, 10d 后端开发 :c2, after b1, 8d 前后端联调完成 :milestone, m3, after c1 c2, 0d section 测试阶段 功能测试 :d1, after c1 c2, 5d 修复与回归 :d2, after d1, 4d section 上线阶段 部署上线 :e1, after d2, 1d 上线完成 :milestone, m4, after e1, 0d### 3.4 工作日与周末的隐藏问题 这是很多刚开始用Mermaid画甘特图的人会遇到的一个细节问题默认情况下日期轴会把周六周日也显示出来而且默认日期轴不是周一开头而是周日开头。比如我前面举例子的项目从6月1日开始6月1日正好是周日渲染出来你会发现时间轴的起点是周日。这在看中文项目的排期时多少有点别扭因为国内团队大多习惯周一作为一周的开始。 要解决这个问题可以在标题和dateFormat后面加上excludes参数 markdown gantt title 工作日排期示例 dateFormat YYYY-MM-DD excludes weekends加了excludes weekends之后周六日会自动从时间轴上剔除任务横条会跳过周末连续的工作日才会排在一起。比如一个从周五开始持续3天的任务渲染出来会显示为周五、下周一、下周二中间周六日不会出现断档。这个参数对项目排期特别实用因为实际工作中绝大多数任务都不应该把周末算进去否则按自然日排期经常会出现“明明预留了5天结果里面有两天是周末”的尴尬情况。除了weekends你还可以指定具体的排除日期比如法定节假日excludes 2025-10-01, 2025-10-02, 2025-10-03注意多个日期之间用英文逗号加空格分隔。我自己做项目排期时通常先写excludes weekends再根据实际公司日历补上节假日。4. 进阶技巧让甘特图真正好用的几个核心配置基础语法掌握了以后你可能会发现渲染出来的图在样式上总有些不满意的点比如时间轴格式不好看、任务描述太长被截断、图上没有显示半成品所需的“进度”细条等。这一部分我把自己实测过的一些实用技巧整理出来每个都配了说明。4.1 自定义时间轴格式Mermaid甘特图默认的时间轴显示格式是类似“2025-06-01”这样的完整日期在某些场景下显得太长。你可以用axisFormat参数来调整时间轴的显示方式。这个参数支持d3时间格式化语法比如你想让日期显示成“6/1”这种短格式gantt title 时间轴格式优化示例 dateFormat YYYY-MM-DD axisFormat %m/%d%m表示两位月份%d表示两位日期。如果你想显示成“2025-06”这种年月的格式就写axisFormat %Y-%m。这看起来是个小功能但在文档里展示时很实用。特别是当你把一个长时间跨度的项目比如6个月放进文档时完整日期会挤在一起换成“第几周”或者“年月”格式会清爽很多。4.2 任务进度和状态标记除了done和active你还可以用类似“50%”这样的进度百分比来标记任务完成度。比如UI设计已经完成了六成可以写成UI设计 :b1, after a2, 7d, 50%渲染后这个任务的横条内部会有一段灰色填充表示完成度。这个功能在做周报、月报、项目进展同步时特别有用。我通常会在每周五把当前所有任务的进度百分比更新一遍然后截图贴在周报里领导和同事一眼就能看出哪些任务滞后了、哪些正常推进。注意进度百分比是跟在持续时长后面用空格分隔。如果你的任务没有指定日期而是用了after依赖同样可以加进度标记。4.3 设置任务标签和样式快捷方式有时候你需要在图上看一些补充信息比如任务负责人、优先级等。Mermaid甘特图本身没有专门的字段但你可以把这类信息拼在任务名称后面用冒号分隔比如前端开发 - 张三 :crit, c1, after b1, 10d这样渲染出来左侧的任务列表就会显示“前端开发 - 张三”虽然不够结构化但胜在简单直接。如果你不想在图上显示这些备注也可以在任务名称里只保留任务名把负责人信息写在代码注释里——Mermaid语法本身支持以%%开头的注释行。4.4 多项目叠加和子任务拆分技巧如果你的需求是要在同一个图上展示两个子项目比如“官网改版”和“CRM系统升级”可以用section来做第一层分组然后在每个section内部用连续的任务名称模拟二级结构。比如gantt title 多项目并行排期 dateFormat YYYY-MM-DD excludes weekends section 官网改版 需求调研 :oa1, 2025-06-01, 5d 前端开发 :oc1, after oa1, 10d section CRM升级 需求梳理 :ca1, 2025-06-02, 3d 后端开发 :cc1, after ca1, 8d这里的关键是不同项目的任务标识符要避免重名。我见过有人把两个section里的任务都叫a1结果依赖关系乱掉的情况。所以跨section时即使Mermaid允许重名最好还是用不同的前缀比如o代表官网、c代表CRM来区分这样可以避免很多不必要的排查成本。4.5 在Excel思维和Mermaid思维之间找到结合点回到热搜词里的“甘特图excel制作教程”。如果你想用Excel做一张复杂的甘特图你需要在单元格里手动画色块、设置条件格式、调整坐标轴过程繁琐且改一次日期就要重来。而用Mermaid在Typora里画甘特图你只需要维护一份类似CSV的任务清单文本然后让图表自动渲染出来。两者本质上都是表达“任务-时间-依赖”这三个维度但Mermaid把表达成本降低了一个量级。如果你团队里已经有用Excel管理任务的习惯你可以引导他们先从Excel表格里把任务清单整理出来列清楚任务名、开始日期、持续天数、前置任务这四列然后一次性翻译成Mermaid语法。这样既能保留Excel在数据统计上的优势又能享受Typora甘特图在可视化上的便利。我在实际工作中已经把“Excel任务清单”作为团队日常维护的源文件把“Typora甘特图”作为每周向管理层汇报的展示成果两者各司其职效率提升非常明显。5. 高频报错与疑难排查我踩过的坑都在这里工具用得越深遇到问题就越多。Mermaid甘特图虽然语法简单但在Typora里实际使用时还是有一些典型问题尤其是渲染报错、日期不显示等。我把这些问题和排查思路整理成了一个速查表方便你直接对照处理。现象可能原因解决办法渲染后提示“Syntax error in text”语法写错比如标点用了中文逗号、引号不匹配检查任务定义里的冒号、逗号是否为英文半角尤其注意复制内容时中文标点混入甘特图完全不显示只有代码代码块语言写成非mermaid或者mermaid语法解析失败确认代码块第一行是mermaid注意不要写成markdown或gantt等任务横条重叠在一起任务之间没有写依赖且开始日期相同为任务增加after依赖或手动错开开始日期时间轴显示为一天但任务横条很长dateFormat与实际输入日期格式不匹配比如dateFormat写了YYYY-MM-DD但输入写成2025/06/01解析会出错周六日出现在时间轴上且排期混乱没有配置excludes weekends在gantt参数里加excludes weekends里程碑显示为普通任务横条里程碑时长写成了非0d确认里程碑时长写0d且加上milestone关键字修改了任务名但图上显示的还是旧名字Typora缓存未刷新或渲染器异常切换一下Typora的源码模式和实时预览模式或者重启Typora中文任务名显示乱码或截断字体或宽度限制导致通常重开文档即可恢复如果持续发生检查系统字体设置5.1 日期格式排查为什么我写的日期不生效这个问题值得单独拿出来讲因为它是很多人第一次画甘特图时最容易碰到的。dateFormat和输入日期必须严格匹配Mermaid支持的日期格式标记主要有YYYY四位年、YY两位年、MM两位月、DD两位日。如果你的dateFormat写的是YYYY-MM-DD那么任务日期就必须写成2025-06-01这种形式如果你写成2025/06/01Mermaid解析时会直接报错。反之如果你用的是斜杠格式dateFormat也要写YYYY/MM/DD。看似是个小细节但一旦日期格式不匹配整个图都可能渲染不出来而不是简单显示某个任务缺失。5.2 进度百分比不显示的原因有些人在任务定义里加了百分比但图上没反应。这通常是因为百分比写错了位置。比如写成任务A :50%, a1, 2025-06-01, 5d这是不对的。百分比应该放在持续时长后面正确写法是任务A :a1, 2025-06-01, 5d, 50%另外百分比必须是合法的数字百分比30%或50%都可以但写成abc%或150%这种就会解析失败或显示异常。注意百分比是和任务状态标记done、active共存的你可以写成:done, a1, 2025-06-01, 5d, 100%表示这个任务100%完成。5.3 Mermaid版本与Typora升级关于热搜词里提到的“typora mermaid怎么升级”这个其实要看Typora版本和Mermaid引擎的集成方式。Typora在安装包内部打入了特定版本的Mermaid库用户层面没有提供单独升级Mermaid引擎的开关。如果你想要新版的Mermaid功能最稳妥的方式是升级Typora本体官方更新日志里通常会注明Mermaid引擎的版本变化。如果你在Typora里遇到某个Mermaid新语法无法识别但同一段代码在Mermaid的官网在线编辑器里却能正常渲染那基本就是Typora内置引擎版本偏旧。这种情况要么等待Typora更新要么在另一个支持较新Mermaid的编辑器里完成图表渲染再把生成的图片贴回文档。5.4 Typora闪退与文档崩溃的预防Typora整体很稳定但在处理特别长的文档、特别复杂的Mermaid图时偶尔也会有卡顿甚至闪退的情况。我自己遇到过一次还是一个包含大量任务和中文描述的甘特图在连续编辑十几分钟后Typora突然闪退。后来排查发现主要是Typora在实时预览模式下每敲一个字符都会触发Mermaid重渲染图表太复杂时内存占用骤增。降低风险的办法有三条一是把代码块的编辑拆成小段写写一段渲染一段而不是一次性粘贴几百行二是在编辑复杂图表的代码块时临时切到源码模式等代码写完再切回预览模式三是及时保存文档Typora有自动恢复机制但别把希望完全寄托在自动恢复上。5.5 公式靠左与文档排版无关但很常用热搜词里有一条“typora 公式怎么靠左”这个虽然和甘特图本身无关但是说明很多人都是在Typora里同时处理正文、公式和图表。如果你想在Typora里让公式靠左而不是居中可以在公式块后加一个特殊标记或者把公式放在行内语法中。具体到行内公式用单个美元符号包裹它天然是跟随文本方向的。块级公式默认居中想强制靠左我试过在公式块末尾加\hfill之类的LaTeX命令部分版本有效但有些版本不生效。如果不是特别频繁需要靠左公式更实用的做法是把公式段落改成普通文本并居中前的自定义样式。这个话题和甘特图扯得有点远但既然很多人搜说明大家习惯把这类问题归到一起我顺便说一句Typora的排版逻辑里很多显示问题都要优先去检查“段落内换行符”和“前后空格”而不是去折腾模板样式。5.6 使用快捷键提高甘特图编辑效率最后分享一个我自己的操作习惯在Typora里写Mermaid代码块时不要每写完一行就切到预览模式看效果这样会频繁打断思路。我建议先一口气把任务描述写完然后用快捷键CtrlShiftKMac上是CmdShiftK快速插入代码块再按CtrlShift逗号或点击右下角的“/”图标切到源码模式编辑写完后切回预览。实际上Typora对代码块的支持很灵活你甚至可以先写一段普通的Markdown列表来列任务等任务清单确定后再转换成Mermaid代码块。这个流程可以让“思考任务结构”和“调试图表效果”两件事彼此分离效率会高很多。我在实际使用中还发现给甘特图的任务名称加上编号比如“1.需求调研”“2.需求评审”比在section里反复嵌套分组更直观尤其当任务数量超过20个的时候。因为Mermaid甘特图的section层级只有一层没有二级三级结构如果你试图用缩进或嵌套来表示层级渲染器会直接忽略。所以简单粗暴的编号法反而是最实用的层级表达方式。6. 总结一下这个方案在我工作流里的真实定位有人可能会问既然Typora的甘特图功能不如专业项目管理软件完整为什么还要推荐我的答案很简单因为它足够轻、足够快、足够透明。轻是指学习成本低一个下午就能完全上手快是指从想法到成图几乎零延迟不用切软件、不用手动排版透明是指所有数据都是纯文本放进Git仓库可以做版本对比换电脑或者换人接手都能无缝衔接。在我实际的工作流里Typora甘特图承担的是“方案沟通”和“进度汇报”这两个角色而不是“任务跟踪”和“资源管理”。做方案时我快速画一张图给团队对齐排期做汇报时我用同一张图更新进度状态截个图放进周报。真正执行层面的每日任务管理我依然会用专门的任务管理工具。这种“各司其职”的分工方式避免了被单一工具绑架的问题也让我在“快”和“重”之间找到了最舒服的平衡点。如果你也想在Typora里尝试甘特图我的建议是从今天手头的一个小项目开始哪怕只有三五个任务先画出来感受一下依赖关系带来的自动排期体验再逐步加入里程碑、关键路径、进度百分比这些进阶要素。用不了几天你大概率会和我一样再也不愿意回Excel里手动拖色块了。