ThinkPHP数据库表结构变更失败需分层排查：先清字段缓存（删除runtime/Data/_fields/对应文件或调用Db::clearCache），再校验MySQL字符集统一性（库、表、字段collation均为utf8mb4_unicode_ci），然后规范使用Migration（命令生成、类名匹配、up/down可逆），最后检查软删除字段delete_time类型与NULL约束是否合规。
ThinkPHP数据库表结构变更失败，通常不是单一原因导致，而是缓存、配置、迁移机制或MySQL底层规则几处联动出问题。修复关键在于分层排查：先确认变更是否真正落到数据库，再检查框架是否感知到新结构，最后验证操作流程是否符合规范。
清除字段缓存，让框架“看见”新字段
新增或修改字段后，add() 和 save() 失败，大概率是字段缓存未更新。ThinkPHP会把表结构缓存到 runtime/Data/_fields/ 或 runtime/schema/ 下的 PHP 文件中，不会自动刷新。
- 直接删除 runtime/Data/_fields/ 目录下对应数据表的缓存文件（如 user.php），或整个 runtime 目录
- 执行命令清空全部缓存：php think clear
- 开发阶段可在 config/database.php 中设置 'fields_cache' => false，禁用缓存便于实时调试
- 代码中主动刷新：\think\facade\Db::clearCache() 或 \think\facade\Db::table('user')->getFieldsType()
检查数据库字符集与排序规则一致性
报错 SQLSTATE[HY000] [1267] Illegal mix of collations 或乱码、插入失败，本质是 MySQL 库、表、字段三级 collation 不统一，尤其在 JOIN、WHERE 或索引字段上容易触发。
- 确认 DSN 中已写死 charset=utf8mb4（如 mysql:host=127.0.0.1;dbname=test;charset=utf8mb4），database.php 中的 'charset' 配置可能被忽略
- 检查 MySQL 服务端配置：character_set_server 和 collation_server 必须为 utf8mb4 和 utf8mb4_unicode_ci（修改 my.cnf 后需重启 MySQL）
- 逐级查实际定义：
SELECT DEFAULT_COLLATION_NAME FROM information_schema.SCHEMATA WHERE SCHEMA_NAME = 'your_db';
SELECT TABLE_NAME, TABLE_COLLATION FROM information_schema.TABLES WHERE TABLE_SCHEMA = 'your_db';
SHOW FULL COLUMNS FROM your_table; - 安全修正表 collation：ALTER TABLE `user` DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;（不重写数据，仅设默认值）
规范使用 Migration 管理结构变更
手动改表再靠模型硬扛，长期必然失控。Migration 是 ThinkPHP 推荐的版本化管理方式，但必须严格遵循格式和逻辑约束。
立即学习“PHP免费学习笔记（深入）”；
- 生成迁移文件必须用命令：php think migrate:create CreateUserTable（自动生成带 14 位时间戳的文件名）
- 类名必须与文件名下划线后部分一致且首字母大写（如 CreateUserTable），继承 think\migration\Migrator
- up() 和 down() 必须成对、可逆；禁止在其中调用 Model，只用 $this->table()->create() 或 Db::name()
- MySQL 8.0+ strict 模式下，字段需显式声明：->useCurrent()、->nullable()、->default(null)
- 执行后用 php think migrate:status 查看状态，比对 think_migration 表确认各环境一致性
软删除字段异常导致 restore() 静默失败
启用软删除后，restore() 返回 false 却无报错，常因 delete_time 字段定义不合规。
- 执行 DESCRIBE user;，确认 delete_time 类型为 DATETIME 或 TIMESTAMP，且 Null 列为 YES，Default 为 NULL
- 若显示 NO 或默认值是固定时间（如 '1970-01-01'），执行：
ALTER TABLE `user` MODIFY COLUMN `delete_time` DATETIME NULL DEFAULT NULL; - 恢复必须走实例：$user = UserModel::onlyTrashed()->find(123); $user->restore();（不能链式调用 onlyTrashed()->where()->restore()）
- 务必判断返回值：if (false === $user->restore()) { /* 记录日志 */ }
