如何在 Laravel 中自定义 Eloquent 模型的主键字段名

当数据库表的主键不是默认的 id（如 des_id），需在对应 Eloquent 模型中显式声明 $primaryKey 属性，否则查询会因找不到 id 字段而报错。

在实际的 Lara vel 项目开发中，很多同学都会遇到这样一个场景：数据库表的主键字段并不是框架默认的 id，而是像 des_id 这样的自定义名称。如果只是简单地把模型写出来，然后直接执行 Destination::where('des_id', $value)->firstOrFail()，表面上看起来没问题，但 Lara vel 在内部进行关联解析或隐式条件引用时，仍然会试图去访问那个不存在的 id 字段。结果呢？一个冷冰冰的 SQLSTATE[42S22]: Column not found: 1054 Unknown column 'tbl_destinations.id' 错误就甩到脸上了。

解决思路其实非常简单——在模型里明明白白地告诉 Eloquent：嘿，主键不是 id，是这个 des_id。一行核心配置就能搞定向下兼容：

做完这步配置之后，有几个细节值得留心：


protected $primaryKey 的值必须和数据库中的真实主键字段名完全一致，大小写和下划线都逃不过。
如果 des_id 不是自增整数，比如是 UUID 或手动维护的字符串，那一定要补上 public $incrementing = false，否则后面 sa ve() 或 create() 时的行为会变得很诡异。
主键类型如果非整型（比如 VARCHAR），顺便加上 protected $keyType = 'string'，防止类型隐式转换搞出幺蛾子。
路由验证规则里的 'exists:mysql.tbl_destinations,des_id' 本身是直接指向字段的，不依赖模型的 $primaryKey，所以这部分不用动。
所有基于模型的查询方式——find()、findOrFail()、关联关系等——都会自动认这个自定义主键。


完成配置后，原来的路由逻辑就能稳稳跑通了：

$destination_id = Destination::where('des_id', $request->destination_id)->firstOrFail();
// ✅ 现在 Eloquent 完全识别 des_id 为主键，不再尝试访问 id 字段


这套做法是 Lara vel 适配非标准数据库设计时的标准实践，说轻量可靠一点不过分。下次再碰到类似表结构，记得先往模型里扔一行 protected $primaryKey，能省掉不少排查错误的时间。