Eloquent 报错和查不到数据的根源在于模型定义、主键配置、时间戳或关联外键等约定未对齐；常见问题包括模型路径/命名空间错误、主键名与类型不匹配、软删除干扰、时间字段缺失或类型不符、关联外键名或中间表名不符合约定。
直接说结论：Eloquent 不是“怎么用”的问题，而是“在哪用错、为什么报错、哪些约定被忽略了”的问题。绝大多数报错和查不到数据，都卡在模型定义、主键配置、时间戳或关联外键这几个地方。
Model类找不到或报错Class 'App\User' not found
这是最常遇到的路径/命名问题。Laravel 9+ 默认模型放在 app/Models 目录，但很多老教程或迁移项目仍沿用 app/User.php 路径，导致自动加载失败。
- 确认文件路径是
app/Models/User.php，且命名空间为namespace App\Models; - 如果用了旧路径（如
app/User.php），必须手动在composer.json的"autoload"中加映射，或运行composer dump-autoload - Artisan 命令生成模型时默认走新路径：
php artisan make:model User→ 自动创建app/Models/User.php - 控制器里引用时别漏掉
use App\Models\User;，不能只写use User;
find() 返回 null 或 where()->first() 查不到数据
表面是查询失败，实际大概率是主键或时间戳配置不匹配。
-
User::find(1)默认按$primaryKey = 'id'查询，如果你的表主键叫user_id，必须在模型中声明：protected $primaryKey = 'user_id'; - 如果主键不是自增整数（比如 UUID 或字符串），还要加：
public $incrementing = false;和protected $keyType = 'string'; -
where()查不到，检查是否启用了软删除：use SoftDeletes;且记录的deleted_at不为NULL→ 改用User::withTrashed()->where(...)->first() - 时间字段（
created_at/updated_at）不存在？关掉它：public $timestamps = false;
关联查询返回空集合，但数据库明明有数据
关联方法名、外键名、表名约定没对齐，Eloquent 就会静默跳过关联。
- 一对多关系中，
User::has('posts')返回空，先确认Post模型里是否定义了正确的外键：return $this->belongsTo(User::class, 'user_id');—— 第二个参数必须显式传，否则默认找user_id，而你的字段可能是author_id - 调用
$user->posts返回空？检查posts()方法里是否用了正确的关联类：return $this->hasMany(Post::class);，而不是post::class（大小写敏感） - 中间表多对多关联（如
users↔roles），中间表名必须是蛇形复数、按字母序：默认是role_user，不是users_roles或user_role - 想让关联字段参与查询（比如查 status=1 的 posts），不能只写
$user->posts，得用带约束的动态关系：$user->posts()->where('status', 1)->get()
save() 失败但没报错，或者 created_at 是 0000-00-00
Eloquent 默认强依赖时间戳字段，一旦字段缺失或类型不对，就会静默失败或填入非法值。
- MySQL 表中没有
created_at字段？要么加字段：$table->timestamps();，要么在模型中关掉：public $timestamps = false; - 字段存在但类型是
DATETIME而不是TIMESTAMP？Laravel 5.8+ 兼容两者，但老版本建议统一用TIMESTAMP - 插入时想跳过时间戳自动填充？临时关闭：
User::withoutTimestamps(function () { User::create([...]); }); -
save()返回false却没提示？加上dd($user->getErrors());查验证错误，或确认是否开启了批量赋值保护（$fillable没配全）
真正难调试的从来不是语法，而是那些“没报错却没干活”的情况——比如外键名拼错一个字母、中间表名顺序颠倒、$timestamps 和数据库字段类型不一致。这些点不一个个对齐，写再多 where() 都白搭。
