ThinkPHP软删除失效主因是字段配置错误：需确保数据库字段名与类型正确（如delete_time为可空datetime）、模型中显式声明$deleteTime、整型时间戳需配置$type映射、避免自动时间戳污染、并清除运行时缓存。
如果您在ThinkPHP中启用软删除功能但数据未按预期逻辑标记或过滤，则很可能是软删除字段配置不正确。以下是设置软删除字段的详细步骤：
一、确认数据库字段命名与类型
软删除字段必须被框架准确识别，其名称和数据类型直接影响delete()行为与查询过滤是否生效。默认字段名为delete_time，且必须为可空的datetime或timestamp类型；若使用整型时间戳，则需同步配置模型类型声明。
1、执行SQL语句添加字段：ALTER TABLE user ADD delete_time DATETIME NULL DEFAULT NULL
2、若已存在该字段但类型为INT，请先修改字段类型：ALTER TABLE user MODIFY delete_time INT NULL
立即学习“PHP免费学习笔记（深入）”；
3、检查字段是否允许NULL：DESCRIBE user，确认delete_time列的Null值为YES
二、在模型中显式声明软删除字段名
ThinkPHP默认仅识别delete_time字段，若数据库中使用deleted_at、is_deleted等其他名称，必须在模型中通过$deleteTime属性强制指定，否则delete()调用将执行物理删除。
1、在模型类顶部导入SoftDelete trait：use think\model\concern\SoftDelete;
2、在模型类定义中加入use SoftDelete;
3、添加protected $deleteTime = 'deleted_at';（字段名须与数据库完全一致）
4、若字段为布尔型（如is_deleted TINYINT(1)），还需设置：protected $defaultSoftDelete = 1;
三、处理整型时间戳字段的类型映射
当delete_time字段类型为INT时，框架默认将其当作字符串处理，导致whereNotNull('delete_time')始终不匹配，软删除数据无法被正确过滤。必须在模型中显式声明字段类型，确保写入与查询逻辑一致。
1、确认数据库字段为INT类型且允许NULL
2、在模型中添加类型声明：protected $type = ['delete_time' => 'integer'];
3、验证写入值是否为合法时间戳（例如1714094040），而非字符串"0"或空字符串
四、避免自动时间戳对软删除字段的污染
若模型启用了自动时间戳（$autoWriteTimestamp = true），而未对delete_time单独控制写入时机，框架可能在新增记录时就将delete_time设为当前时间，导致刚插入的数据即被判定为“已删除”。必须确保delete_time仅在delete()调用时赋值。
1、移除$createTime或$updateTime中对delete_time的误配
2、确保模型中未设置：protected $updateTime = 'delete_time';
3、保留$deleteTime = 'delete_time'，但不将其列入自动写入字段列表
五、清除运行时缓存以加载新字段结构
数据库字段变更后，ThinkPHP可能仍使用旧的模型结构缓存，导致withTrashed()、onlyTrashed()等方法失效或查询结果异常。必须强制刷新缓存，使模型重新读取表结构。
1、删除runtime/cache/目录下的全部文件
2、删除runtime/model/目录下对应模型的缓存文件（如User.php）
3、执行一次任意模型查询触发结构重载：User::count();
