Carbon 3要求PHP≥8.1，需先确认版本；命名空间须改为use Carbon\Carbon；构造函数移除时区参数，改用parse()->tz()；addWeekday()等方法已删除，需替换为addWeekdays(1)等；启用严格模式防日期解析隐患。
Carbon 2 升级到 3 之前必须确认 PHP 版本
Carbon 3.x 要求 PHP ≥ 8.1，硬升会直接失败。运行 php -v 确认当前版本；若为 PHP 7.4–8.0，composer require nesbot/carbon:^2.60 是唯一安全选择。Laravel 9+ 默认带 Carbon 2，Laravel 10+ 才默认用 v3 —— 但如果你项目里 composer.json 锁了 "nesbot/carbon": "2.*"，哪怕 PHP 8.2 也会卡在 v2。
命名空间和构造函数是迁移时最常报错的两个点
旧代码里 use Carbon\Carbon\Carbon; 或 new Carbon\Carbon() 全部失效，必须改成 use Carbon\Carbon;。构造函数行为也变了：Carbon::now('Asia/Shanghai') 合法，但 new Carbon('now', 'Asia/Shanghai') 会抛 ArgumentCountError —— 因为 v3 移除了第二个参数。
- 全局搜索替换所有
use Carbon\Carbon\开头的声明 - 把
new Carbon($time, $tz)改成Carbon::parse($time)->tz($tz)或直接Carbon::parse($time, $tz) - 别漏掉测试文件、命令行脚本、Traits 里的引用 —— 这些地方最容易被 IDE 全局替换忽略
废弃方法不兼容，但替代方案很直白
addWeekday()、subWeekday()、isLeapYear() 这三个方法在 v3 中彻底删除，不是弃用警告，是直接不存在。错误信息通常是 Call to undefined method Carbon\Carbon::addWeekday()。
-
addWeekday()→addWeekdays(1) -
subWeekday()→subWeekdays(1) -
isLeapYear()→isLeap() - 注意：这些方法名变更不涉及逻辑变化，只是统一命名风格，不用重读文档，但必须批量改代码
Carbon::parse() 的“柔化”行为没变，但严格模式更关键了
v3 没改 Carbon::parse('2026-02-30') 自动转成 2026-03-02 的逻辑，这在表单或 API 接口里仍是隐患。开发阶段务必加 Carbon::useStrictMode(true)，生产环境必须包裹 try/catch 处理异常，而不是依赖它“自动修好”。
- 别用
Carbon::parse(null)或空字符串 —— 它会静默回退到当前时间，掩盖参数缺失 - 数据库字段含零日期（如
'0000-00-00'）时，parse()仍会失败，得先过滤或用createFromFormat('Y-m-d', $str) ?: Carbon::now() - CI 流水线里如果没开严格模式，这类问题可能只在上线后暴露
时区和本地化配置本身没变，但 v3 对未显式设置时区的容忍度更低——一旦服务器系统时区是 UTC，而你又没调 date_default_timezone_set('Asia/Shanghai') 或 Carbon::now('Asia/Shanghai')，时间偏移就不是“可能”，而是“一定”。
