通过GitHub CI/CD使用Umzug运行Sequelize迁移时遇模块缺失问题

一、排查依赖安装问题 #

• 确保CI环境安装全量依赖：GitHub Actions默认可能以生产环境模式安装依赖，会跳过devDependencies。如果迁移依赖ts-node、typescript这类开发依赖，需修改安装命令：

  - name: Install dependencies
    run: npm install --include=dev
    # 或用npm ci（需提交package-lock.json保证版本一致）
    # run: npm ci
  

• 对齐本地与CI的Node.js版本：在GitHub Actions YAML中指定和本地一致的Node版本，避免版本差异导致模块解析异常：

  - name: Setup Node.js
    uses: actions/setup-node@v4
    with:
      node-version: '20.x' # 替换为你本地的Node版本
  

• 确认锁文件已提交：package-lock.json或yarn.lock要同步到仓库，用npm ci替代npm install可保证CI依赖版本和本地完全一致。

二、修正模块路径与TS配置 #

• 处理TypeScript编译问题：如果Umzug配置是.ts文件，本地用ts-node直接运行，但CI环境需确保：
  1. 先执行TypeScript编译：

     - name: Build TypeScript
       run: tsc
     

  2. 执行编译后的JS文件，而非源TS文件：比如原命令是ts-node umzug.ts，改为node dist/umzug.js（需对应tsconfig.json的outDir配置）。
  3. 若直接在CI用ts-node执行，需确保ts-node已在依赖中，命令改为：

     - name: Run migrations
       run: npx ts-node umzug.ts
     

• 检查相对路径正确性：确认migrator.js或Umzug配置中的模块导入路径、迁移文件路径，是否因CI工作目录与本地不同导致找不到。比如本地在项目根目录执行，CI若需进入子目录，可调整命令：

  - name: Run migrations
    run: cd ./scripts && node migrator.js
  

• 验证TS配置：检查tsconfig.json的outDir、rootDir、moduleResolution等配置，确保编译后的文件结构和Umzug配置中的路径匹配。

三、检查Umzug配置与执行逻辑 #

• 确认迁移路径配置：如果迁移文件路径使用了环境变量或动态拼接，需在CI中设置对应环境变量，避免路径解析错误。比如Umzug配置中的：

  migrations: {
    path: process.env.MIGRATIONS_PATH || './migrations'
  }
  

  需在GitHub Actions中添加环境变量：

  - name: Run migrations
    run: node dist/migrator.js
    env:
      MIGRATIONS_PATH: './dist/migrations'
  

• 排查误报的模块错误：部分情况下，数据库连接失败可能被伪装成模块找不到的报错，需确认CI中的数据库连接字符串、账号密码等环境变量是否正确配置。

四、替代方案 #

• 改用Sequelize官方CLI：Sequelize自带的迁移工具生态更成熟，CI配置更简单。步骤：
  1. 安装依赖：npm install sequelize-cli --save-dev
  2. 初始化配置：npx sequelize-cli init
  3. 在CI中执行迁移：

     - name: Run migrations
       run: npx sequelize-cli db:migrate
       env:
         DB_HOST: ${{ secrets.DB_HOST }}
         DB_USER: ${{ secrets.DB_USER }}
         DB_PASSWORD: ${{ secrets.DB_PASSWORD }}
         DB_NAME: ${{ secrets.DB_NAME }}
     

• 迁移脚本改为纯JS：将Umzug配置和迁移文件改为JavaScript，避免TypeScript编译带来的路径和依赖问题，直接在CI中用node执行。
• 容器化迁移过程：用Docker打包迁移环境，本地和CI使用相同的镜像，消除环境差异。比如编写Dockerfile包含所有依赖和迁移脚本，CI中直接运行容器执行迁移。

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