Laravel 9升级10后Sail环境触发Carbon\UnitNotConfiguredException

问题现象 #

• Laravel 9 升级到 10 后，本地 Sail 环境登录时抛出 Carbon\Exceptions\UnitNotConfiguredException，错误信息：Unit microseconds have no configuration to get total from other units
• 问题出在 Illuminate\Support\Sleep 类里创建 Carbon 间隔对象并添加微秒的逻辑
• 生产服务器完全正常，只有 Sail 本地环境出问题

可能原因 #

核心原因是 Sail 容器内的 Carbon 依赖版本、PHP 版本或扩展配置和生产环境不匹配。Laravel 10 对 Carbon 版本有明确要求，Sail 默认镜像的依赖版本或 ext-intl 扩展状态可能影响了 Carbon 的单位处理逻辑。

解决步骤 #

1. 统一 Carbon 版本

   • 进入 Sail 容器执行 composer show nesbot/carbon，查看当前 Carbon 版本，和生产环境对比
   • 如果版本不一致，在项目 composer.json 的 require 段锁定 Laravel 10 兼容的 Carbon 版本，比如：

     "nesbot/carbon": "^2.66.0"
     

   • 回到 Sail 容器执行 composer update nesbot/carbon 更新依赖

2. 检查并启用 PHP intl 扩展

   • 执行 sail shell 进入容器
   • 输入 php -m | grep intl，确认 intl 扩展已安装
   • 如果没装，修改项目根目录的 docker-compose.yml，在 PHP 服务的 build.args 里加 INSTALL_INTL: 'true'：

     services:
         laravel.test:
             build:
                 context: ./vendor/laravel/sail/runtimes/8.2
                 dockerfile: Dockerfile
                 args:
                     WWWGROUP: '${WWWGROUP}'
                     INSTALL_INTL: 'true'
     

   • 重建容器：sail down -v && sail build --no-cache && sail up -d

3. 临时修复 Sleep 类的微秒处理（应急方案）
   如果上面的方法都没效果，可以临时修改框架代码绕过问题：

   • 找到 vendor/laravel/framework/src/Illuminate/Support/Sleep.php
   • 将原有的微秒拼接逻辑改成毫秒统一处理：

     // 原代码
     $interval = CarbonInterval::milliseconds($milliseconds)->addMicroseconds($microseconds);
     // 修改后
     $totalMilliseconds = $milliseconds + ($microseconds / 1000);
     $interval = CarbonInterval::milliseconds($totalMilliseconds);
     

   • 注意：这只是临时 workaround，后续要靠版本统一或官方修复彻底解决

内容的提问来源于stack exchange，提问作者Flobbo