$casts仅负责类型转换，不处理字段名映射；解决字段名不一致需用访问器/修改器或重写getAttribute/setAttribute方法，并注意$fillable、查询及JSON字段的适配。
为什么 $casts 不能解决字段名不一致的问题
因为 $casts 只负责类型转换（比如把字符串转成数组或日期），它不碰字段名。当你数据库字段叫 user_name，但模型里想用 name 访问，$casts 完全无能为力——它连字段映射这层逻辑都不参与。
常见错误是写完 protected $casts = ['user_name' => 'string'] 就以为能直接 $user->name，结果报错 Undefined property: App\Models\User::$name。本质是 Eloquent 默认只识别数据库字段原名，不做别名映射。
用 $fillable / $guarded + 访问器/修改器手动桥接
这是最可控、兼容性最好的做法，适合字段少、映射规则固定的情况。核心思路：让模型“假装”有那个属性，再在底层读写真实字段。
- 在模型中定义访问器：
public function getNameAttribute() { return $this->user_name; } - 定义修改器：
public function setNameAttribute($value) { $this->attributes['user_name'] = $value; } - 确保
name在$fillable中（否则create()或fill()会忽略它）：protected $fillable = ['name', 'email']; - 注意：修改器必须操作
$this->attributes数组，不能用$this->user_name = $value，否则会触发无限递归（因为赋值又调用修改器）
用 getAttribute() 和 setAttribute() 全局接管
当字段映射较多（比如十几个字段都要重命名），一个个写访问器太重复。可以覆盖模型的两个核心方法，统一做映射表驱动：
立即学习“PHP免费学习笔记（深入）”；
protected $fieldMap = [
'name' => 'user_name',
'phone' => 'mobile_phone',
'status' => 'is_active',
];
public function getAttribute($key)
{
if (array_key_exists($key, $this->fieldMap)) {
return parent::getAttribute($this->fieldMap[$key]);
}
return parent::getAttribute($key);
}
public function setAttribute($key, $value)
{
if (array_key_exists($key, $this->fieldMap)) {
parent::setAttribute($this->fieldMap[$key], $value);
return;
}
parent::setAttribute($key, $value);
}
⚠️ 注意：这样做后，$fillable 必须写逻辑字段名（如 name），而不是数据库字段名；否则批量赋值会失败。另外，Eloquent 的原始查询（selectRaw、withCount 等）不受影响，它们仍操作原始字段。
第三方包 renatomarinho/laravel-page-speed 不相关，别踩坑
搜索时容易误点进一些名字带 “mapping” 或 “attribute” 的包，比如这个页面加速包——它完全不处理字段映射。真正可用的轻量方案只有 laravel-attribute-mapper（需手动维护映射表）或干脆不用包。
复杂点在于：JSON 字段、关联关系、where() 查询里的字段名不会自动被映射。比如 User::where('name', 'John')->get() 实际执行的是 WHERE name = ?，不是 WHERE user_name = ?。这种场景必须显式写成 where('user_name', 'John')，或者配合 toBase()->select(...) 手动构造查询。
