**注意：**用户旅程图的高亮新旧版本会正常显示。
用户旅程图
mermaid官方网站文档教程链接(英文)
社区维护的中文文档站
1、新版本语法
journey如下仅是基础的常用功能语法，如需更全面内容可参考官网教程文档
任务行格式
- 兼容旧版：
任务: 评分: 角色 - 新增：
任务: 角色（评分可选）
简化版：打开App: 用户 兼容版：打开App: 4: 用户- 兼容旧版：
评分
支付订单: 2: 用户 / 支付订单: 用户兼容 1-5 整数，省略时无情绪曲线
多角色分隔
下单: 4: 用户, 系统 / 下单: 4: 用户 系统兼容英文逗号，新增空格分隔（更易读）
section 命名
section ⚠️ 支付阶段（痛点）支持 Emoji（⚠️/💡）、标点、特殊符号
空行 / 换行
section 间加空行（代码更清晰）支持空行分隔阶段，不影响渲染
注释规则
- 单行注释：
%% 注释内容（必须以%%开头，可放在行首 / 行尾）； - 多行注释：无原生支持，需每行加
%%；
- 单行注释：
特殊规则（避坑重点）
核心差异：旧版强制要求评分，新版评分可选、支持更多样式，且 Typora 版本决定兼容性；
实用建议：优先用新版语法，新版功能更新 Typora；
避坑点：section 名称加 Emoji 仅新版支持，旧版会显示乱码，建议写在任务名中。
2、代码示例
示例1
journey title 用户核心旅程 section 发现阶段 看到广告/推荐: 5: 用户 了解产品价值: 4: 用户 section 决策阶段 对比竞品/看评价: 3: 用户 注册/下载: 5: 用户 section 使用阶段 首次体验功能: 4: 用户 完成核心任务: 5: 用户 遇到问题: 2: 用户 section 留存阶段 再次使用: 4: 用户 分享/推荐: 3: 用户 续费/复购: 4: 用户示例2
journey title 电商App用户全旅程（含多角色+情绪评分） section 1. 发现与引流 刷短视频看到广告: 4: 用户, 推荐系统 点击广告进入商品页: 3: 用户, 前端 浏览商品详情: 4: 用户, 商品系统 加入购物车: 5: 用户, 购物车系统 section 2. 注册与登录（⚠️ 痛点：验证码慢） 点击登录/注册: 2: 用户, 账号系统 手机号+验证码登录: 1: 用户, 短信服务 完善个人信息: 3: 用户, 账号系统 section 3. 下单与支付 进入结算页: 4: 用户, 订单系统 选择地址/支付方式: 3: 用户, 地址/支付系统 提交订单并支付: 2: 用户, 支付网关, 财务系统 支付成功: 5: 用户, 订单系统 section 4. 履约与售后（💡 机会：物流实时提醒） 查看订单物流: 4: 用户, 物流系统 收到商品验货: 3: 用户, 快递员 申请售后/评价: 4: 用户, 客服, 评价系统3、效果示例
示例1
示例2
4、老版本语法
journey新版本功能可以支持更丰富的内容，旧版写法差异明显，头部声明没有变化，不推荐使用就不介绍太多了。
journey title 电商用户下单简易旅程（旧版语法） section 浏览商品 打开电商App: 4: 用户 搜索目标商品: 3: 用户 查看商品详情: 4: 用户 section 下单支付 加入购物车: 5: 用户 提交订单: 3: 用户 完成支付: 2: 用户 section 收货评价 等待物流: 3: 用户 确认收货: 4: 用户 发布商品评价: 5: 用户5、新旧版本差异
新旧版本差异比较大，如下对比
| 语法规则 | 旧版（Mermaid v8.x） | 新版（Mermaid v9.x+） | 典型示例 | 报错 / 兼容说明 |
|---|---|---|---|---|
| 任务行基础格式 | 必须包含「任务：评分：角色」，三者缺一不可 | 1. 兼容旧版完整格式2. 支持简化格式「任务：角色」（评分可选） | 旧版：登录: 3: 用户新版：登录: 用户 | 旧版写登录: 用户会直接报错；新版两种写法均生效 |
| 评分值要求 | 仅支持 1-5 的整数（无其他取值） | 兼容 1-5 整数，无评分时不显示情绪曲线 | 旧版：支付: 6: 用户（报错）新版：支付: 用户（无评分） | 旧版评分超 1-5 范围报错；新版无评分仅展示流程 |
| 多角色分隔符 | 仅支持英文逗号（,），无其他分隔方式 | 兼容英文逗号，支持空格分隔（更易读） | 旧版：下单: 4: 用户, 系统新版：下单: 4: 用户 系统 | 旧版用空格分隔角色会识别为单个角色；新版两种方式均正确 |
| Section 命名格式 | 仅支持纯文本（字母 / 数字 / 中文），不支持特殊字符 | 支持 Emoji（⚠️/💡）、标点、特殊符号 | 旧版：section 注册流程新版：section ⚠️ 注册流程（痛点） | 旧版 section 加 Emoji 会显示乱码；新版完全兼容 |
| 注释语法 | 仅支持行尾注释（任务: 3: 用户 %% 注释） | 支持行尾注释、单独注释行（%% 单独注释） | 旧版：%% 单独注释（无效）新版：%% 单独注释（生效） | 旧版单独注释行会被识别为任务导致报错；新版支持任意位置注释 |
| 空行 / 换行 | 不支持空行，换行过多会导致渲染错乱 | 支持空行分隔阶段，换行不影响渲染 | 旧版：section 间加空行（渲染错位）新版：section 间加空行（更清晰） | 旧版复杂图加空行易乱；新版可通过空行优化代码排版 |
- 基础场景：语法规则差异明显
- 高级场景：journey新增专属功能
6、版本兼容性
- Typora 版本 < 1.0
- 旧版 Typora 用新版语法（无评分）会渲染失败
- 旧版 section 加 Emoji 会显示乱码 / 报错
- 低版本 Typora 无法使用新版特性
- 新版渲染更美观，旧版仅能靠评分体现情绪
- Typora 版本 ≥ 1.0
- 复杂多角色旅程图新版可读性更高
- 新版可定制化程度更高，适配复杂图的视觉区分
- 复杂分支旅程图新版能更清晰展示逻辑
- 绘制超 10 个 section 的复杂图时新版体验更好
- 如何查版本：Typora → 帮助 → 关于 Typora（可看到 Typora 版本）。
