如何避免EF Core迁移及自定义迁移操作（自定义SQL）的部署错误

该问题的核心原因是SQL Server的脚本执行逻辑：整段脚本会先完成预编译再执行，即使IF NOT EXISTS的条件永远为假，包裹在块内的过时SQL依然会在预编译阶段触发语法错误、对象不存在错误，最终导致整个脚本执行失败，和EF Core的迁移执行逻辑无关。

可行解决方案 #

方案1：动态执行自定义SQL（改动最小，优先推荐） #

把所有migrationBuilder.Sql()里的SQL语句用EXEC()或者sp_executesql包裹，动态SQL只会在代码块真正执行时才编译，不会触发全局预编译错误。
示例：
原来的写法：

migrationBuilder.Sql("UPDATE Users SET IsValid = 1 WHERE Phone IS NOT NULL");

修改后的写法：

migrationBuilder.Sql("EXEC(N'UPDATE Users SET IsValid = 1 WHERE Phone IS NOT NULL')");

如果SQL内部包含单引号，转义为两个单引号即可。

方案2：压缩历史迁移（适合项目稳定后清理冗余代码） #

当所有已部署的环境（生产、测试等）都已经跑完所有历史迁移后，可以合并所有历史迁移为一个初始快照，彻底清除过时的自定义SQL：

1. 删除项目Migrations目录下的所有历史迁移文件
2. 执行dotnet ef migrations add SquashedInitial生成全新的初始迁移
3. 在所有已部署的数据库的__EFMigrationsHistory表中插入本次生成的迁移ID记录，避免已完成部署的数据库重复执行初始迁移
   后续生成的幂等脚本就不会再携带过时的历史自定义SQL，从根源避免问题。

方案3：改为运行时执行迁移 #

放弃预生成SQL脚本的部署方式，发布阶段直接运行dotnet ef database update命令执行迁移：

• EF Core运行时只会加载未执行过的迁移，已经执行过的历史迁移根本不会被加载，自然不会触发旧SQL的编译问题
• 注意需要保证发布代理节点可以访问目标数据库、安装对应版本的.NET SDK、拥有数据库读写权限

方案4：自定义SQL增加前置判断 #

如果需要保留历史迁移的兼容性，可以在自定义SQL中先判断依赖对象是否存在，再结合动态SQL执行：

migrationBuilder.Sql(@"
IF EXISTS(SELECT * FROM sys.columns WHERE Name = N'Phone' AND Object_ID = Object_ID(N'Users'))
BEGIN
    EXEC(N'UPDATE Users SET IsValid = 1 WHERE Phone IS NOT NULL')
END
");

最佳实践建议 #

• 能使用EF Core原生迁移API（比如RenameColumn、AddColumn）实现的操作，不要手写自定义SQL，原生API生成的SQL天然兼容幂等脚本的预编译逻辑
• 手写自定义SQL时尽量避免依赖后续会被修改/删除的表、列等schema对象，减少SQL过时概率

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