Mermaid ERD 导入与导出初学者指南

1. Dr.ERD 如何使用 Mermaid

Mermaid 的 erDiagram 语法用一段文本描述表、字段和关系。Dr.ERD 可以读取 .mmd、.mermaid 文件或粘贴的文本，打开为可编辑的模型，再把完成后的模型写回同样的文本形式。本教程会用 Mermaid 导入一个三表订单模型，完善后再次导出为 Mermaid。

• 导入：把 .mmd、.mermaid 文件或粘贴的 Mermaid 文本打开为新模型。
• 导出：把模型保存为 Mermaid 文本，即导出格式中的“Mermaid · MMD”。
• 标准 erDiagram 语法没有地方书写布局（坐标）、数据字典，以及 NOT NULL、默认值、自增等详细约束。Dr.ERD 导出时会在图的下方附加一行 %% drerd-metadata-v1 注释，把这些细节保留在其中，重新导入该文件时再恢复。
• 其他 Mermaid 工具只画图，会忽略这行注释。删除或改动注释，就会丢失它所保护的 Dr.ERD 细节，或者在导入时收到元数据校验错误的提示。

2. 准备示例 Mermaid 代码

下面的代码就是本教程要导入的 Mermaid 文本，包含会员（members）、订单（orders）和订单明细（order_items）三张表以及两个关系。代码框上的复制按钮只会把当前显示的文本复制到剪贴板，复制本身不会创建或打开文档；导入要在下一步自行执行。

• 文本以 erDiagram 开头。去掉空行和 %% 注释后，第一行必须是它，否则无法导入。
• members ||..o{ orders 表示左侧为 1、右侧为零或多个，中间的两个点表示非标识关系。
• 长度和小数位写在括号中，例如 VARCHAR(100)、NUMERIC(12,2)。
• PK、FK、UK 写在字段名之后，例如 BIGINT member_id FK。

erDiagram
  members {
    BIGINT id PK
    VARCHAR(100) name
  }
  orders {
    BIGINT id PK
    BIGINT member_id FK
    TIMESTAMP created_at
  }
  order_items {
    BIGINT id PK
    BIGINT order_id FK
    VARCHAR(100) product_name
    INTEGER quantity
    NUMERIC(12,2) unit_price
  }
  members ||..o{ orders : "places"
  orders ||..o{ order_items : "contains"

3. 准备工作文件夹

无需账号，在本地完成。Dr.ERD 无需安装，在桌面版 Chrome 或 Edge 中运行。选择工作文件夹后，ERD 会保存为该文件夹中的 .drerd 文件，默认不会上传到服务器。团队协作需要 Google 登录，团队文档保存到所选团队；AI 对话是可选功能。本教程只用本地文件夹即可完成。

1. 选择“启动编辑器”进入工作区。
2. 在“选择工作区”中选择保存 .drerd 文件的文件夹。
3. 浏览器询问文件夹访问权限时选择“允许”。

• 桌面版 Chrome 与 Edge 支持选择并保存文件夹。
• 如需使用 AI 对话，只有在自行完成 API 设置后发送的消息，才会把当前 ERD 上下文发送给你选择的提供方。

4. 导入 Mermaid

在文件列表中打开“导入”菜单，选择“导入 Mermaid”。对话框要求选择词典语言和目标数据库，再选择文件或粘贴文本。目标数据库会保存在模型中并用于之后的导出，因此必须在导入前选择。本教程选择与示例相同的 PostgreSQL 18。选择“文本”会打开以 erDiagram 行开头的粘贴框。

1. 在文件列表中点击“导入”，再选择“导入 Mermaid”。
2. 在目标数据库中选择 PostgreSQL 18。
3. 选择“文本”，把第 2 步的代码粘贴到粘贴框中。
4. 点击“确认”，模型会作为临时模型在编辑器中打开；点击“保存”才会在文件夹中留下文件。

• 若要导入文件，请在“导入 Mermaid”中选择“导入文件”，再选择 .mmd 或 .mermaid 文件。
• 导入的表会自动排布在画布上。
• 未选择目标数据库时，导入不会继续。
• 错误会带行号提示，修正该行后重新导入即可。

5. 检查表、键和类型长度

导入后的模型包含三张表和两个关系。请核对物理名、类型以及 PK、FK 标记是否与示例一致，并确认长度与小数位。有关系线并不等于创建了外键字段；Mermaid 中的 FK 标记只表示“该字段是外键候选”，并不会指明引用哪个字段。刚导入时，两个关系的引用键和 FK 对应都是空的。

1. 用“编辑表”打开每张表，核对字段的物理名和类型。
2. 确认 id 字段带 PK，member_id 与 order_id 带 FK。
3. 确认对应的类型一致：members.id 是 BIGINT，orders.member_id 也必须是 BIGINT。
4. 确认长度与小数位：VARCHAR(100) 长度为 100，INTEGER 没有长度，NUMERIC(12,2) 长度为 12、小数位为 2。

• 预期结果：三张表（members、orders、order_items）和两个关系。
• 只有 FK 标记不会配置关系，引用键与 FK 对应要在第 7 步自行设置。
• 下面的示例是没有元数据注释的纯 erDiagram，标准语法无法表示 NOT NULL，因此导入的字段除主键外都是“允许 NULL”。

6. 把所有字段设为必填

Mermaid 没有表示字段必填的写法，所以要在导入后设置。本教程最终要求字段必须有值，因此把三张表共 10 个字段的“允许 NULL”全部关闭。

1. 在“编辑表”中选择字段。
2. 在“列详情”中关闭“允许 NULL”。
3. 对 members、orders、order_items 的 10 个字段全部重复一次。

• 关闭“允许 NULL”的字段在导出 SQL DDL 时会变为 NOT NULL。Mermaid 图中不显示，但 Dr.ERD 导出附带的元数据注释会保留它。
• 把 Dr.ERD 导出的 Mermaid 原样导回 Dr.ERD 时，该设置也会恢复。但没有注释的纯 erDiagram，或被其他工具删除注释的文件，除主键外的字段会再次变成“允许 NULL”，请重新检查。
• 本示例没有自增（Identity）。插入数据时，请先有父表数据，再自行填写 id 的值。

7. 配置两个关系

导入的关系还不知道哪个子字段引用哪个父字段。请打开每个关系，设置引用键（Source key）与 FK 对应。未设置时关系保持“未配置”，SQL DDL 导出会被拒绝；Mermaid 导出虽然仍可进行，但要得到正确的外键，必须把两个关系都设置好。

1. 打开 members → orders 关系，在引用键中选择 PK。该关系的 PK 就是 members.id，引用键列表里是 PK 与 UK 项目，而不是字段。
2. 在 FK 对应中把左侧 id 这一行选为 orders 的 member_id。保留默认的“添加列”会新建字段，因此不要选它；标识关系保持关闭，然后点击“应用”。
3. 打开 orders → order_items 关系，在引用键中选择 PK。该关系的 PK 就是 orders.id。
4. 在 FK 对应中把左侧 id 这一行选为 order_items 的 order_id，标识关系保持关闭，然后点击“应用”。

• 两个关系都是非标识（0..N），父键不会加入子表主键。
• 一个会员可以有零个或多个订单，一个订单可以有零条或多条明细。
• 引用键缺失，或外键类型与被引用字段不一致时，会提示错误。
• Mermaid 中的 FK 标记只是线索。有 FK 标记但没有设置 FK 对应的关系仍属于未配置。

8. 保存并导出 Mermaid

用 Ctrl+S 或 Cmd+S 保存到工作文件夹的 .drerd 文件，然后在导出菜单中选择“Mermaid · MMD”，保存为 .mmd 文件。导出的文本与下面的示例形状相同，包含三张表和两个非标识关系（||..o{）。每次导出都可以自行选择保存位置。

1. 按 Ctrl+S 或 Cmd+S 保存 .drerd 文件。
2. 在导出菜单中选择“Mermaid · MMD”。
3. 选择 .mmd 文件的保存位置。
4. 打开导出的文件，确认三张表和两个关系仍然保留。

• 布局、字典和详细约束不会出现在图中。Dr.ERD 导出时会附加 %% drerd-metadata-v1 注释加以保留，并在导入时恢复。
• 关系名取自模型，下面示例中的关系名是 places 和 contains。
• Mermaid 无法表达的名称、注释或关系名会保留在 .drerd 项目文件中，并会给出相应说明。

erDiagram
  members {
    BIGINT id PK
    VARCHAR(100) name
  }
  orders {
    BIGINT id PK
    BIGINT member_id FK
    TIMESTAMP created_at
  }
  order_items {
    BIGINT id PK
    BIGINT order_id FK
    VARCHAR(100) product_name
    INTEGER quantity
    NUMERIC(12,2) unit_price
  }
  members ||..o{ orders : "places"
  orders ||..o{ order_items : "contains"

9. 常见问题排查

导入与导出之间最常出现的几种情况及检查方法。

• 头部错误：去掉空行和 %% 注释后，第一行必须正好是 erDiagram，否则会在该行报错。
• 不支持的语法：关系两侧需要各两个字符，例如 members ||..o{ orders。不匹配的行会以“不支持的 ERD 语法”并带行号提示。
• 类型不一致：外键字段必须与被引用字段类型相同，members.id 是 BIGINT 时 orders.member_id 也必须是 BIGINT。
• 无法导出 SQL：存在未配置的关系时 SQL DDL 导出会被阻止，并提示设置引用键与 FK 对应。N:M 关系需要先改为中间表。
• 必填字段缺失：如果仍有字段的“允许 NULL”没有关闭，结果就与本教程不一致。

10. 下一步

你已经完成用 Mermaid 导入模型、完善、保存并再次导出为 Mermaid 的全过程。接着可以在其他指南中了解如何在编辑器中从零创建同一个模型，以及如何导出 SQL DDL。

• Mermaid 文本适合粘贴到文档和评审中，.drerd 文件可以直接在编辑器中重新打开。
• SQL DDL 导出会针对 PostgreSQL 18、MySQL 8.4/InnoDB 或 Oracle 19c 生成同一个模型。

• 创建第一个 ERD
• 导出 SQL DDL
• 使用指南总览
• 打开编辑器