# 迁移

> Fabric.js 迁移不用重写：直接打开 Fabric 5 的 toJSON 结果，升级到 Fabric.js 6 或 7，旧文档在打开时自动升级。

Source: https://fabricjs-document-engine.jscrate.dev/zh/docs/guides/migration
Last updated: 2026-09-28

大多数编辑器已经有一批用普通 Fabric.js JSON 保存的项目。做 Fabric.js 迁移通常意味着要写一个转换器。在这里，旧文件可以直接打开，并在打开时自动升级。

## 打开普通 Fabric.js JSON

Fabric 5、Fabric.js 6 或 Fabric.js 7 的 `canvas.toJSON()` 普通输出，都可以直接打开：

```ts
await engine.importFabricJson(savedJsonText, {
  id: "plan-42",
  metadata: { source: "old editor" },
});
```

`loadDocument` 和 `load(id)` 也能识别普通 Fabric.js JSON，所以你现有应用保存的项目不需要单独导入就能打开。用 `load(id)` 打开的文档会保留这个 id，下一次保存时存成新格式。

## 从 Fabric 5 升级到 Fabric.js 6 或 7

这个包需要 Fabric.js 6 或 7。保存的数据不会阻碍升级：

- Fabric 5 保存的 JSON 会经过迁移步骤打开。Fabric.js 6 和 7 仍然接受 Fabric 5 的旧类型名。
- Fabric 6 和 Fabric.js 7 的默认原点不同。文档总是保存 `originX` 和 `originY`，所以用一个版本保存的文件，在另一个版本里也能正确打开。

你自己的代码请按官方的 Fabric.js 升级指南修改。存下来的文件不需要任何 Fabric.js 迁移脚本。

## 格式版本

每份文档都记录了它的 `schemaVersion`。将来某个大版本改变格式时，旧文档会在打开时一步步升级。

- 发生升级时，`load:success` 会带上 `migratedFrom`。
- 某一步失败会以 `MIGRATION_FAILED` 拒绝，`error.migrationFrom` 给出起始版本。
- 更新版本的包保存的文档会以 `UNSUPPORTED_SCHEMA` 拒绝，而不是被错误读取。

## 在服务器上升级文件

`migrateDocument` 和 `detectSchemaVersion` 在 Node 里无需画布即可运行，适合批量任务：

```ts
import { detectSchemaVersion, migrateDocument } from "fabricjs-document-engine";

if (detectSchemaVersion(stored) === 0) {
  const { document } = migrateDocument(stored, {
    canvasWidth: 1200,
    canvasHeight: 800,
  });
  await saveUpgraded(document);
}
```

`detectSchemaVersion` 对文档返回 `1`，对普通 Fabric.js JSON 返回 `0`，其他情况返回 `undefined`。测试过的版本见[兼容性](https://fabricjs-document-engine.jscrate.dev/zh/docs/production/compatibility)。