MikroORM v6 → v7 迁移指南

概述

MikroORM v7 是一次重大版本升级。核心变化：原生 ESM、knex→kysely、装饰器拆包、Node.js 22.17+/TypeScript 5.8+ 最低要求。本技能覆盖迁移的所有关键路径，避免常见陷阱。

环境要求

项目	v6	v7
Node.js	18+	22.17+
TypeScript	5.0+	5.8+
模块系统	CJS/ESM	原生 ESM

迁移步骤总览

Step 1: 包替换

# 1. 替换核心包
pnpm remove @mikro-orm/knex
pnpm add @mikro-orm/sql

# 2. 安装装饰器包（如使用装饰器）
pnpm add @mikro-orm/decorators

# 3. SQLite 驱动选择（见 Edge-Ready 参考）
# better-sqlite3: pnpm add @mikro-orm/sqlite
# node:sqlite / bun:sqlite / D1: pnpm add @mikro-orm/sql kysely

Step 2: Import 路径更新

- import { Entity, PrimaryKey, Property } from '@mikro-orm/core';
+ import { Entity, PrimaryKey, Property } from '@mikro-orm/decorators/legacy';
+ // 或 ES spec 装饰器:
+ // import { Entity, PrimaryKey, Property } from '@mikro-orm/decorators/es';

- import { ... } from '@mikro-orm/knex';
+ import { ... } from '@mikro-orm/sql';

关于 ES vs Legacy 装饰器的选择和配置，必须阅读 references/decorators.md。

Step 3: API 替换

- em.persistAndFlush(entity)
+ em.persist(entity).flush()

- em.removeAndFlush(entity)
+ em.remove(entity).flush()

- em.nativeInsert(Entity, data)
+ em.insert(Entity, data)

- em.getKnex()
+ em.getKysely()

- orm.getSchemaGenerator().createSchema()
+ orm.schema.create()

- em.find('User')
+ em.find(User)

- const orm = MikroORM.initSync({ ... })
+ const orm = new MikroORM({ ... })

完整 API 变更对照表见 references/api-changes.md。

Step 4: Entity 定义适配

v7 提供两种实体定义方式：

方式 A: defineEntity（推荐，新项目）

import { defineEntity, PrimaryKey, Property } from '@mikro-orm/core';

const UserEntity = defineEntity({
  class: class User {},
  tableName: 'user',
  properties: {
    id: p.uuid().primary(),
    name: p.string(),
    email: p.string().nullable(),
    createdAt: p.datetime().onCreate(() => new Date()),
  },
});

方式 B: Legacy 装饰器（现有项目迁移）

import { BaseEntity, type Opt } from '@mikro-orm/core';
import { Entity, PrimaryKey, Property } from '@mikro-orm/decorators/legacy';

@Entity({ tableName: 'user' })
export class User extends BaseEntity {
  @PrimaryKey({ type: 'uuid', onCreate: () => crypto.randomUUID() })
  id!: string & Opt;

  @Property({ type: 'text' })
  name!: string;

  @Property({ type: 'text', nullable: true })
  email?: string;
}

两种方式的详细对比和场景建议见 references/decorators.md。

Step 5: 默认值变更检查

配置项	v6 默认	v7 默认	影响
加载策略	joined	balanced	to-many 关系改为独立查询
forceUtcTimezone	false	true	现有非 UTC 数据会被错误解读
嵌入属性前缀	absolute	relative	嵌套嵌入列名可能变化
@Transactional 传播	REQUIRES_NEW	REQUIRED	默认加入已有事务
processOnCreateHooksEarly	false	true	onCreate 在 em.create 中立即执行

关键: 如果现有数据以本地时区存储，升级前必须决定是否迁移数据或显式设 forceUtcTimezone: false。

Step 6: Edge/Bun/node:sqlite 适配

如需在 Edge Runtime、Bun 或使用 node:sqlite 运行 MikroORM，必须阅读 references/edge-ready-sqlite.md。

实体定义方式选择

需要实体定义？
  ├─ 新项目 / 无历史 decorator 代码 → defineEntity（类型推断更好）
  ├─ 现有项目迁移 / 大量 decorator 实体 → Legacy decorator
  └─ TC39 decorator 环境（Node 22.6+原生支持）→ ES spec decorator

常见错误快速定位

症状	原因	修复
Cannot find module '@mikro-orm/knex'	包重命名	替换为 @mikro-orm/sql
persistAndFlush is not a function	API 移除	em.persist(entity).flush()
nativeInsert is not a function	方法重命名	em.insert(Entity, data)
Decorator SyntaxError (SWC/Vite)	装饰器编译未配置	见 decorators.md
Value for X.id is required	onCreate 未配置	PrimaryKey 加 onCreate
TypedArray.prototype.join incompatible	Blob clone 问题	见 known-issues.md
string reference not supported	字符串引用移除	改为类引用 () => Entity
Schema diff 出现意外变更	默认值变更	检查 Step 5 默认值表

更多已知问题和解决方案见 references/known-issues.md。

迁移检查清单

• Node.js ≥ 22.17，TypeScript ≥ 5.8
• @mikro-orm/knex → @mikro-orm/sql
• 安装 @mikro-orm/decorators，更新 import
• 替换 persistAndFlush / removeAndFlush
• 替换字符串引用为类引用
• 更新 SchemaGenerator / Migrator / Seeder 方法名
• QueryBuilder .execute() / .getResult() 替代直接 await
• 更新 driverOptions 去掉 connection 嵌套
• 检查 forceUtcTimezone 对现有数据的影响
• 更新 Formula/Index/Check 回调签名（quote 辅助函数）
• 运行 orm.schema.update({ diff: true }) 检查 schema 变更
• 运行 typecheck 和测试验证

参考文档

• 装饰器迁移: ES vs Legacy vs defineEntity
• Edge-Ready SQLite 配置
• 完整 API 变更对照表
• 已知问题与解决方案