carbon 是一个独立的 php 日期处理类库，非 composer 插件；需通过 composer require nesbot/carbon 安装，正确使用需引入 autoload、设置时区与本地化，并注意与 datetime 的兼容性。
Carbon 是什么，为什么不能“安装插件”
Carbon 不是 Composer 的插件，也不是需要额外“安装”的扩展模块——它是一个独立的 PHP 类库，由 nesbot/carbon 提供。你执行 composer require nesbot/carbon，本质是把 Carbon 的源码下载进 vendor/ 并注册自动加载，不是启用某个开关或钩子。
常见错误现象：Class 'Carbon\Carbon' not found，往往是因为没运行 composer install 或没引入 autoload（比如忘了 require 'vendor/autoload.php';）。
- 使用场景：只要项目用 PHP 写、需要比原生
DateTime更友好的日期操作（如today()、subDays(3)、diffForHumans()），就适合直接 require 它 - 不要试图在
composer.json里写"plugins": ["carbon"]—— Composer 根本不认这种写法，会报错Invalid argument supplied for foreach()或静默忽略 - Carbon v2 要求 PHP >= 7.18，v3 要求 PHP >= 8.0；如果项目还在用 PHP 7.0，必须锁死版本：
composer require nesbot/carbon:^2.60
怎么正确 require 并开始用 Carbon
装完之后，不需要额外配置，也不用改 php.ini 或重启服务。Carbon 通过 Composer 自动加载机制即可直接 new 实例或调静态方法。
典型误操作：在类文件顶部写 use Carbon; —— 这不对，正确命名空间是 use Carbon\Carbon;，或者直接用全限定名 \Carbon\Carbon::now()。
- 最简可用示例：
require 'vendor/autoload.php'; use Carbon\Carbon; echo Carbon::now()->addWeek()->toDateString(); // 输出类似 2024-06-15
- 如果你用 Laravel，Carbon 已预装且自动 alias 了
Carbon，可直接Carbon::yesterday()，但注意：Laravel 10+ 默认用的是 Carbon v2，若要 v3 需手动升级并检查第三方包兼容性 - 别在循环里反复 new 大量 Carbon 实例——它比原生
DateTime开销略高；高频场景（如日志时间格式化）建议复用或缓存格式化器
时区、语言、格式这些坑怎么绕开
Carbon 默认用系统时区，但多数 Web 应用该设为应用时区（如 Asia/Shanghai），否则 Carbon::now() 返回的时间可能和预期差 8 小时。
常见错误现象：Carbon::parse('2024-01-01')->format('Y-m-d H:i:s') 输出时间带 UTC 偏移却没意识到，导致数据库存错、前端显示错。
- 全局设置时区（推荐在框架启动时做一次）：
Carbon::setTestNow(null); Carbon::setLocale('zh'); date_default_timezone_set('Asia/Shanghai'); -
Carbon::createFromFormat()对格式敏感：'Y-m-d'和'y-m-d'表示不同年份位数，输错会返回false而不是抛异常；建议加判断：$date = Carbon::createFromFormat('Y-m-d', $input) ?: throw new InvalidArgumentException(...); - 中文本地化需额外 require
carbon/laravel（仅 Laravel）或手动require vendor/nesbot/carbon/src/Carbon/Lang/zh.php；否则diffForHumans()仍是英文
和原生 DateTime 混用要注意什么
Carbon 继承自 DateTime，所以能传给任何接收 DateTimeInterface 的函数（比如 PDO 绑定参数、date_format()），但反向不成立：你不能把 DateTime 当作 Carbon 调用 startOfMonth()。
容易踩的坑：从数据库查出的 DateTime 对象，想链式调用 Carbon 方法——得先转一下：Carbon::instance($datetime)。
- 性能提示：Carbon 构造函数内部做了不少封装逻辑，纯性能敏感场景（如每秒处理万级时间戳）建议优先用原生
DateTimeImmutable+date_create_immutable() - 序列化行为不同：Carbon 默认序列化为字符串（ISO8601），而
DateTime序列化后是对象结构；JSON encode 时表现一致，但 var_export 或调试时容易误判类型 - 别在 Carbon 实例上调
clone—— 它已实现__clone，但语义上更推荐用copy()或avoidMutation()配合不可变模式
真正麻烦的从来不是装不上，而是默认时区没设、本地化没加载、混用时忘了 instance 包装——这些点不显眼，但一出问题就得翻半小时日志。
