Spring Kotlin项目Flyway 9.3无法识别时间戳前缀迁移文件

环境与配置 #

• 技术栈：Kotlin + Spring
• Flyway版本：Flyway Plugin 9.3（未显式指定flyway-core版本）
• Flyway Gradle配置：

flyway {
    url = "url"
    user = "user"
    password = "password"
    locations = arrayOf("filesystem:src/main/resources/db/migration/common")
    placeholderPrefix = "\${flyway:timestamp}"
    sqlMigrationPrefix = "\${flyway:timestamp}"
}

问题现象 #

在db/migration/common目录下使用202203311000__create-something-table.sql格式的迁移文件时，执行迁移命令报错：

Unrecognised migration name format: 202203311000__create-le-table.sql

但将文件前缀改为V1、V2这类格式后，Flyway可正常识别并执行迁移。

补充说明：

1. 报错信息中的文件名存在笔误，实际文件名格式为202203311000__create-something-table.sql
2. Flyway validateMigrationName输出结果（中文翻译版）：

验证失败：迁移文件名格式不符合Flyway的命名规范。当前文件名未包含有效的版本前缀（如V开头的版本号），或格式与配置的sqlMigrationPrefix不匹配。

原因分析 #

1. 配置冲突：配置中设置了sqlMigrationPrefix = "\${flyway:timestamp}"，但Flyway的sqlMigrationPrefix用于指定迁移文件的固定前缀（默认是V），并非动态时间戳变量。该配置会让Flyway期望所有迁移文件以${flyway:timestamp}字符串为前缀，而非实际时间戳数值，因此无法识别现有命名格式的文件。
2. 版本适配问题：未显式指定flyway-core版本时，Gradle自动匹配的兼容版本可能存在逻辑异常，导致时间戳格式的版本号识别失效（Flyway默认支持数字版本号，时间戳属于数字版本的延伸，但需要正确的前缀配置）。

解决方案 #

方案1：使用默认前缀+时间戳版本号 #

保留Flyway默认的sqlMigrationPrefix（即V），将迁移文件名改为V202203311000__create-something-table.sql格式，同时移除配置中的sqlMigrationPrefix设置：

flyway {
    url = "url"
    user = "user"
    password = "password"
    locations = arrayOf("filesystem:src/main/resources/db/migration/common")
    placeholderPrefix = "\${flyway:timestamp}"
    // 移除sqlMigrationPrefix配置，使用默认值V
}

方案2：自定义前缀并统一命名格式 #

若坚持使用时间戳相关命名，需将sqlMigrationPrefix设为固定前缀字符串，同时调整文件名格式。例如设置前缀为T，文件名改为T202203311000__create-something-table.sql：

flyway {
    url = "url"
    user = "user"
    password = "password"
    locations = arrayOf("filesystem:src/main/resources/db/migration/common")
    placeholderPrefix = "\${flyway:timestamp}"
    sqlMigrationPrefix = "T"
}

方案3：显式指定flyway-core版本 #

声明与Flyway Plugin 9.3匹配的flyway-core版本（9.3.x），避免自动版本适配的潜在问题：

dependencies {
    implementation("org.flywaydb:flyway-core:9.3.0")
}

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