
Laravel 默认将模型日期属性序列化为 ISO 8601 格式(如 2021-10-19T22:00:00.000000Z),但可通过 Carbon 全局设置字符串输出格式,实现所有日期字段在 JSON 序列化时自动按统一格式(如 'Y-m-d')输出,避免手动 format() 或空值判断。
laravel 默认将模型日期属性序列化为 iso 8601 格式(如 `2021-10-19t22:00:00.000000z`),但可通过 carbon 全局设置字符串输出格式,实现所有日期字段在 json 序列化时自动按统一格式(如 `'y-m-d'`)输出,避免手动 `format()` 或空值判断。
在 Laravel 中,模型的 $casts 属性(如 'date_rec' => 'datetime:Y-m-d')仅影响 Eloquent 查询结果直接转数组/JSON 的行为,而对模型实例中手动访问属性(如 $model->date_rec)或自定义数组方法(如 asListItem())不生效——此时返回的是原生 Carbon 实例,其默认 __toString() 输出为完整 ISO 8601 时间戳。
要真正实现「全局日期序列化格式」,关键在于统一控制 Carbon 实例的字符串表示行为。Laravel 底层使用 Carbon 处理日期,而 Carbon 提供了静态方法 Carbon::setToStringFormat(),可全局覆盖所有 Carbon 实例调用 __toString()(即隐式或显式转换为字符串)时的格式。
✅ 推荐方案:在服务提供者中全局设置
在 app/Providers/AppServiceProvider.php 的 boot() 方法中添加:
use Carbon\Carbon;
public function boot()
{
// 全局设定 Carbon 实例转字符串的默认格式(影响 toJSON()、json_encode()、API 响应等)
Carbon::setToStringFormat('Y-m-d');
}
配置后,所有场景均自动生效:
- ✅ $model->date_rec 在 JSON 序列化中变为 "2021-10-19"
- ✅ asListItem() 中 "try_1" => $this->date_rec 直接输出 "2021-10-19"
- ✅ 关联模型、集合、API 资源(Resource)中的日期字段同步受益
- ✅ 自动处理 null 值:null 仍为 null,不会触发错误(与手动 ->format() 不同)
⚠️ 注意事项:
- 此设置影响整个应用中所有 Carbon 实例的字符串输出,包括 now()、today() 等。若需局部差异化,请改用 Carbon::parse($date)->format('Y-m-d') 显式格式化。
- 若使用 Laravel 9+ 且启用了 date_casts 配置(config/database.php),该设置优先级低于 setToStringFormat(),无需额外配置。
- 如需恢复默认行为,可调用 Carbon::resetToStringFormat()。
? 进阶提示:
若需更精细控制(如不同环境不同格式,或仅对 API 响应生效),可结合 Laravel 的 JsonSerializable 接口或在 ApiResource 中重写 toArray(),但全局 setToStringFormat() 是最简洁、侵入性最小的解决方案。











