ThinkPHP软删除需模型配置、数据库字段、调用方式三者严格对齐：数据库加NULLable的delete_time字段；模型引入SoftDelete trait并配置$deleteTime；删除必须用模型方法而非Db类；查询默认过滤已删数据，可用onlyTrashed()或withTrashed()控制范围。
ThinkPHP数据删除失败，多数不是代码写错，而是配置、字段或逻辑链路没对上。核心问题集中在软删除启用状态、数据库字段定义、查询链式顺序和环境加载这四块。
软删除配置是否真正生效
模型里只写 use SoftDelete 不够，必须同时满足三项：
- 引入 trait：use think\model\concern\SoftDelete;
- 类内声明：use SoftDelete;
- 明确定义字段：protected $deleteTime = 'delete_time';（名称必须与数据库字段完全一致）
低版本 TP6.0.0～6.0.7 还需强制开启：protected $useSoftDelete = true;。漏掉任一环，delete() 就会执行物理删除，restore() 则静默返回 false。
delete_time 字段是否合规
字段类型和约束直接影响软删成败：
立即学习“PHP免费学习笔记（深入）”；
- 类型必须是 DATETIME / TIMESTAMP / INTEGER，不能是 VARCHAR 或 TINYINT
- 必须允许为 NULL：
NULL属性为 YES，Default建议设为NULL - 若用整型存时间戳，模型中要加类型映射：protected $type = ['delete_time' => 'integer'];
字段定义错误时，restore() 尝试写入 NULL 会被 MySQL 拒绝，但框架不报错——查数据库发现 delete_time 依然有值，就是这个原因。
删除与恢复操作的写法陷阱
常见无效写法及对应解法：
-
批量 restore 失效：不要写
UserModel::onlyTrashed()->where(...)->restore()，它不作用于结果集。应先取 ID：$ids = UserModel::onlyTrashed()->where(...)->column('id');，再直写更新：UserModel::whereIn('id', $ids)->update(['delete_time' => null]); -
withTrashed() 放错位置：必须置于链式调用最前端，如
UserModel::withTrashed()->where(...)->select()；写成where()->withTrashed()无效 -
关联模型未同步软删：主表调了
withTrashed()，关联表默认仍过滤已删数据。需在关联方法中显式加->withTrashed()，或闭包预载时指定
环境与缓存干扰排查
看似逻辑正确却删不动，可能卡在环境层：
- .env 文件必须放在项目根目录，且 APP_DEBUG = true 才会加载；否则
env('DB_HOST')返回 null - 修改模型后未刷新 schema 缓存，旧配置仍在生效：运行
php think optimize:schema - 数据库连接本身异常，先用命令行验证：
mysql -h 127.0.0.1 -P 3306 -u root -p；注意别用 localhost，避免 Unix socket 路径错位
不复杂但容易忽略
