TypeORM 1.0 正式发布：近十年等待后的现代化重塑

预计阅读时间：8 分钟

从 2016 年诞生到 2025 年终于推出 1.0，TypeORM 走了一条漫长的路。这个被无数 NestJS 项目默认绑定的 ORM，长期停留在 0.x 版本，维护节奏一度让人担忧。1.0 的到来不只是版本号的跃迁——它意味着平台要求的现代化、废弃 API 的清理、安全与迁移流程的加固，以及社区维护信心的重建。

为什么要等这么久

TypeORM 早期采用"0.x 永远是开发版"的惯例，但实际使用规模早已超出这个定位。大量生产项目直接依赖 0.x，版本号本身成了心理障碍：团队不敢放心升级，贡献者不确定哪些改动算"breaking"。长期累积的废弃 API、过时的依赖和未修复的 bug 让代码库越来越沉重。

1.0 的核心意图就是切断历史包袱——一次性移除所有标记为 deprecated 的接口，把最低运行要求拉到现代水平，为后续迭代腾出空间。

平台要求的跃迁

1.0 明确将运行环境对齐到 ECMAScript 2023。这意味着：

Node.js 最低版本提升，旧版本（如 Node 12/14/16）不再受支持，项目需要运行在符合 ES2023 特性的 Node 版本上（Node 18+ 已全面覆盖）。
依赖树瘦身，一批过时或不再必要的外部依赖被移除，减小了安装体积和潜在安全风险。
语言特性可用，代码库内部和用户侧都能直接使用 structuredClone、Array.prototype.findLast 等 ES2023 新增 API，不再需要 polyfill 或绕行。

如果你的项目还卡在旧 Node 版本上，升级 TypeORM 1.0 前必须先解决运行环境。

废弃 API 清理与迁移影响

0.x 阶段积累的废弃方法在 1.0 中全部移除。常见的变动方向包括：

旧式连接配置方式被替换为更规范的 DataSource 体系（这一切换在 0.3 已开始，1.0 彻底收尾）。
部分装饰器签名调整，参数顺序或可选字段发生变化。
一些内部工具方法不再公开导出。

升级时最直接的风险点在于：如果你仍在使用任何带 @deprecated 标记的调用，1.0 下会直接编译/运行报错。建议在升级前全局搜索 deprecated 用法，逐项替换。

安全与迁移流程的加固

1.0 对安全相关环节做了针对性强化：

依赖树中已知存在漏洞的包被剔除或替换。
SQL 注入防护在更多边界场景下得到补全，尤其是原始查询片段拼接的检测。
迁移（Migration）流程的生成与执行逻辑修复了多个长期报告的 bug，比如重复生成、顺序错乱、回滚不完整等问题。

迁移是 ORM 升级中最容易踩坑的环节，1.0 的改进让 typeorm migration:generate 和 typeorm migration:run 的行为更可预测。

实践：从 0.x 升级到 1.0 的最小可运行示例

下面是一个使用 TypeORM 1.0 + PostgreSQL 的最小项目骨架，可以直接复制运行。假设你已经安装了 Node 18+ 和 PostgreSQL。

项目初始化：

mkdir typeorm-1.0-demo && cd typeorm-1.0-demo
npm init -y
npm install typeorm@1.0.0 pg reflect-metadata
npm install -D typescript ts-node @types/node @types/pg

tsconfig.json：

{
  "compilerOptions": {
    "target": "ES2023",
    "module": "commonjs",
    "strict": true,
    "emitDecoratorMetadata": true,
    "experimentalDecorators": true,
    "outDir": "dist",
    "rootDir": "src"
  },
  "include": ["src"]
}

src/data-source.ts：

import "reflect-metadata";
import { DataSource } from "typeorm";
import { User } from "./entity/User";

export const AppDataSource = new DataSource({
  type: "postgres",
  host: "localhost",
  port: 5432,
  username: "postgres",
  password: "postgres",
  database: "typeorm_demo",
  synchronize: true, // 仅用于演示，生产环境请用 migration
  logging: true,
  entities: [User],
});

src/entity/User.ts：

import { Entity, PrimaryGeneratedColumn, Column } from "typeorm";

@Entity()
export class User {
  @PrimaryGeneratedColumn()
  id: number;

  @Column()
  name: string;

  @Column({ unique: true })
  email: string;
}

src/index.ts：

import { AppDataSource } from "./data-source";
import { User } from "./entity/User";

async function main() {
  await AppDataSource.initialize();
  console.log("数据源已连接");

  const user = new User();
  user.name = "张三";
  user.email = "zhangsan@example.com";

  const saved = await AppDataSource.manager.save(user);
  console.log("已保存用户:", saved);

  const found = await AppDataSource.manager.findOne(User, {
    where: { email: "zhangsan@example.com" },
  });
  console.log("查询结果:", found);

  await AppDataSource.destroy();
}

main().catch((err) => {
  console.error(err);
  process.exit(1);
});

运行：

# 确保 PostgreSQL 已启动，并创建目标数据库
psql -U postgres -c "CREATE DATABASE typeorm_demo;"

# 执行
npx ts-node src/index.ts

如果一切正常，你会看到连接日志、插入记录和查询结果的输出。这个示例刻意使用 DataSource 而非旧式 createConnection，正是 1.0 要求的写法。

升级前的检查清单

在把现有项目推到 1.0 之前，建议按以下步骤排查：

检查项	操作
Node.js 版本	确认 >= 18，否则先升级运行环境
废弃 API 调用	全局搜索 `@deprecated` 或 0.x 文档中标记为废弃的方法，逐项替换
`createConnection` 用法	替换为 `new DataSource(...)` + `initialize()`
第三方依赖兼容	检查 @nestjs/typeorm 等集成包是否已发布兼容 1.0 的版本
迁移文件	在 1.0 下重新 `migration:generate`，对比输出是否与旧文件一致
CI 流水线	更新 Node 版本镜像和测试脚本

1.0 是一次断崖式升级——没有废弃过渡期，旧用法直接报错。但这也意味着升级完成后，你面对的是一个更干净、更安全、更可维护的代码库，后续版本迭代有望回到正常节奏。对于一个被广泛依赖的基础设施项目来说，这份决断来得不算早，但来得正是时候。