$append不生效的主因是访问器未触发或模型未序列化；需确保$appends命名与访问器方法严格匹配、方法public无参、返回非null，且未被$hidden/$visible屏蔽，关联字段须预加载。
$append 不生效，八成是访问器没被触发，或模型根本没走序列化流程。
为什么 $appends 里的字段在 toJson() 里不出现
最常踩的坑是：你以为模型“自动”追加了字段，其实它只在真正调用 toArray() 或 toJson() 时才执行访问器逻辑。如果只是 dd($model) 或直接打印对象，$appends 完全不会起作用。
-
$appends数组里的字符串必须和访问器方法名「去掉get和Attribute后的驼峰名」严格一致：比如getFullNameAttribute()→'full_name'，写成'fullname'或'Full_Name'都无效 - 访问器方法必须是
public、无参数、非静态；返回值不能是null（toJson()默认过滤null值，建议兜底如return $this->first_name . ' ' . ($this->last_name ?? '') ?: ''） - 检查是否被
$hidden或$visible意外屏蔽——$appends字段同样受这两者控制 - 若字段来自关联模型（如
getAvatarUrlAttribute()里用了$this->avatar?->path），但没预加载avatar关系，就会返回null或触发 N+1
在 API Resource 里 $appends 失效怎么办
JsonResource 是独立转换层，它完全不读取模型的 $appends。即使模型写了 $appends = ['permissions']，Resource 的 toArray() 也不会自动包含它。
- 必须手动加：
'permissions' => $this->permissions，靠这行触发访问器并塞进响应 - 别在 Resource 里重写同名逻辑（比如再写一遍权限计算），否则维护成本翻倍、测试难覆盖
- 如果字段依赖请求上下文（如当前用户角色），不要把判断硬编码在模型访问器里；改用 Resource 构造时传参，或通过
with()注入上下文
用 append() 动态追加比全局 $appends 更安全
全局 $appends 会让所有接口都带上字段，哪怕前端根本不需要。而 append() 只作用于具体集合，按需注入，避免冗余传输。
- 只能对 Eloquent Collection 调用，即必须在
get()之后：User::where(...)->get()->append('full_name')；where()->append()->get()会报错 - 支持批量：
->append(['full_name', 'avatar_url', 'is_online'])，名称全部小写蛇形，Laravel 自动匹配getXXXAttribute - 单个模型实例也能用：
$user->append('permissions')，但注意它返回的是新实例，原对象不变 - 性能更可控：没调用
append()就不执行访问器，彻底规避“为不用的字段买单”
哪些字段根本不该放进 $appends
Larastan 会直接报错的三类字段，说明它们违背了 $appends 的设计本意：它只该承载纯计算、无副作用、不查库的属性。
- 数据库字段本身（如
'email'、'name'）：这些本就自动出现在 JSON 里，加进去纯属重复 - 修改型访问器（如
getDisplayNameAttribute()里调了$this->update(...)）：访问器不该有副作用 - 需要远程请求或文件读取的字段（如拼接头像 URL 时调了
Storage::url()且磁盘配置未缓存）：每次序列化都发请求，响应时间直接飙升
真正该放进去的，只有像 getCreatedAtFormattedAttribute() 这种一行格式化、零 IO、确定性返回的字段。其他情况，优先考虑 Resource 层处理或预计算后存入临时属性。
