Carbon必须用composer require安装，手动复制文件会导致类找不到或功能异常；需引入vendor/autoload.php；空值解析应避免直接parse；时区与本地化需显式配置。
Carbon 库必须用 composer require 安装，不能手动复制文件
Carbon 不是单文件类库，它依赖 nesbot/carbon 包和底层的 symfony/polyfill-mbstring 等支持包。手动下载 PHP 文件放进项目会导致 Class 'Carbon\Carbon' not found 或时区/本地化失效。
- 运行
composer require nesbot/carbon（推荐不带版本号，让 Composer 自动选兼容当前 PHP 的最新稳定版） - 如果项目已锁死 PHP 版本（比如 PHP 7.4），可加约束：
composer require nesbot/carbon:^2.60（Carbon 2 支持 PHP 7.1+） - PHP 8.0+ 项目建议直接用 Carbon 3：
composer require nesbot/carbon:^3.0，但注意它移除了部分静态别名（如Carbon::now()仍可用，Carbon::today()被标记为废弃）
require 后要确认 autoload 生效，否则 new Carbon() 会报错
Composer 安装后不会自动加载类，必须确保项目中已引入 vendor/autoload.php。常见错误是只执行了 composer require，却忘了在脚本开头 require 'vendor/autoload.php';。
- 检查入口文件（如
index.php或测试脚本）第一行是否包含：require __DIR__ . '/vendor/autoload.php'; - 如果用框架（Laravel、Symfony），这步通常由框架自动完成，但写独立 CLI 脚本或单元测试时极易漏掉
- 运行
composer dump-autoload可刷新自动加载映射，解决某些 IDE 提示“未定义类”但实际能运行的问题
Carbon 实例化时传空字符串或 null 会触发意外异常
很多人习惯写 new Carbon('') 或 Carbon::parse(null) 想获取当前时间，但 Carbon 2/3 对空输入更严格：会抛出 InvalidFormatException，而不是静默 fallback 到 now()。
- 安全写法统一用
Carbon::now()、Carbon::today()或new Carbon()（无参构造函数明确表示“当前时间”） - 从用户输入解析时，先判空：
Carbon::parse($input ?: 'now')或!empty($input) ? Carbon::parse($input) : Carbon::now() - 注意
Carbon::parse('0000-00-00')在 MySQL 零日期场景下也会失败，需提前过滤或用Carbon::createFromFormat('Y-m-d', $date) ?: Carbon::now()
时区和语言环境配置容易被忽略，导致格式化结果不符合预期
Carbon 默认使用系统时区（通常是 UTC），且中文本地化需额外加载语言包。不显式设置的话，$date->formatLocalized('%A') 可能输出英文，$date->diffForHumans() 时间差描述也可能是英文。
- 全局设时区：
Carbon::setLocale('zh');和date_default_timezone_set('Asia/Shanghai');都要调，前者影响本地化方法，后者影响底层date()行为 - 中文需额外 require 语言包（Carbon 3 已内置，Carbon 2 需
composer require symfony/translation并注册翻译器） - 单个实例临时设时区更安全：
Carbon::now('Asia/Shanghai')->format('Y-m-d H:i:s')，避免污染全局状态
Carbon 的坑不在安装命令本身，而在于它和 PHP 原生时间函数、时区配置、本地化机制深度耦合——装上了不代表能用对，尤其在跨服务器环境或老项目里，date_default_timezone_get() 返回什么、locale -a 是否有 zh_CN.utf8，都会让同一段代码表现不同。
