我之前在 React Native 项目里用 TypeORM 做过类似的迁移操作，刚好能给你一些落地性的建议，解决你提到的这些问题：

一、迁移文件的创建方式 #

你可以借助 TypeORM 的 CLI 工具生成迁移模板，适配 React Native 环境只需要简单调整配置：

• 先确保项目安装了 typeorm 和对应的存储驱动（比如 @react-native-community/sqlite），然后在项目根目录创建 ormconfig.js 配置文件：

module.exports = {
  type: "sqlite",
  database: "your-app-db.db",
  location: "default", // React Native SQLite 默认存储位置
  entities: ["src/models/**/*.ts"],
  migrations: ["src/migrations/**/*.ts"],
  cli: {
    migrationsDir: "src/migrations" // 指定迁移文件存放目录
  }
};

• 在 package.json 里添加 CLI 脚本命令：

"scripts": {
  "typeorm": "ts-node node_modules/typeorm/cli.js"
}

• 运行命令生成迁移文件：npm run typeorm migration:generate -- -n AddNewFieldToUser，这个命令会自动对比当前实体模型和数据库结构，生成包含升级/回滚逻辑的模板，不用手动从零写起。

二、迁移文件的格式与内容 #

迁移文件不是纯 SQL，而是基于 TypeORM 提供的 API 封装（当然也支持原生 SQL），这样能保证跨数据库兼容性：

一个典型的迁移文件结构如下：

import { MigrationInterface, QueryRunner, Column } from "typeorm";

export class AddNewFieldToUser1690000000000 implements MigrationInterface {
    // 应用迁移时执行的逻辑
    public async up(queryRunner: QueryRunner): Promise<void> {
        // 方式1：用TypeORM抽象API（推荐，跨数据库兼容）
        await queryRunner.addColumn("user", new Column({
            name: "avatar_url",
            type: "text",
            nullable: true
        }));
        
        // 方式2：用原生SQL（适合复杂操作）
        // await queryRunner.query(`ALTER TABLE user ADD COLUMN avatar_url TEXT`);
    }

    // 回滚迁移时执行的逻辑
    public async down(queryRunner: QueryRunner): Promise<void> {
        await queryRunner.dropColumn("user", "avatar_url");
        // 原生SQL写法：await queryRunner.query(`ALTER TABLE user DROP COLUMN avatar_url`);
    }
}

• up 方法对应升级操作，down 对应回滚操作（生产环境一般很少回滚，更多是写新迁移修复问题）。

三、迁移文件的存放位置 #

按照 ormconfig.js 里配置的 migrationsDir 路径存放即可，比如 src/migrations 目录。

注意：要确保这个目录被 Metro 打包工具识别，在 metro.config.js 里检查 watchFolders 和 resolver 配置，避免打包时遗漏迁移文件。

四、自动执行迁移的核心配置 #

你提到的 migrationsRun: true 就是实现自动迁移的关键，在数据库连接配置里开启它，每次应用启动时 TypeORM 会自动检查未执行的迁移并运行：

import { createConnection } from "typeorm";

const initDatabase = async () => {
    await createConnection({
        type: "sqlite",
        database: "your-app-db.db",
        location: "default",
        entities: [require("./models/User").default],
        migrations: [require("./migrations/AddNewFieldToUser1690000000000").default],
        migrationsRun: true, // 开启启动时自动执行迁移
        synchronize: false, // 重要：禁止自动同步实体到数据库，否则会覆盖迁移逻辑
    });
};

initDatabase();

⚠️ 务必把 synchronize 设为 false，否则 TypeORM 会直接根据实体结构修改数据库，完全忽略你的迁移文件，这在生产环境非常危险！

五、React Native 环境的特殊注意事项 #

• 因为 React Native 是客户端环境，没有 Node.js 的文件系统 API，所以迁移文件要尽量用 ES 模块或 CommonJS 格式，避免语法打包错误。
• 测试迁移时一定要在模拟器/真机上验证，本地开发环境的数据库和设备上的数据库是完全隔离的。
• 如果遇到迁移执行失败的情况，可以查看设备上的数据库文件（比如 iOS 可以通过 Xcode 导出，Android 可以通过 adb 拉取），检查 typeorm_metadata 表（TypeORM 用来记录已执行迁移的表）的状态。

内容的提问来源于stack exchange，提问作者Joris416