本文详解如何解决 laravel sail 启动时报 “your composer dependencies require php >= 8.1.0, but you are running 8.0.14” 的典型问题——根本原因在于 sail 容器内 php 版本未同步更新，而非宿主机环境配置错误。
本文详解如何解决 laravel sail 启动时报 “your composer dependencies require php >= 8.1.0, but you are running 8.0.14” 的典型问题——根本原因在于 sail 容器内 php 版本未同步更新，而非宿主机环境配置错误。
你执行 php -v 看到的是 宿主机（WSL）的 PHP 8.1.8，而 Sail 报错中 “You are running 8.0.14” 指的是 Docker 容器内部运行的 PHP 版本——这是两个完全隔离的运行时环境。Laravel Sail 的 laravel.test 服务由 Docker 构建并启动，其 PHP 版本由 docker-compose.yml 中指定的构建上下文（build.context）和底层镜像共同决定，与宿主机 PHP 设置无关。
要彻底修复该问题，请严格按以下三步操作：
✅ 第一步：修正 docker-compose.yml 中的运行时路径与镜像标识
打开项目根目录下的 docker-compose.yml，定位 laravel.test 服务，确保 build.context 指向 Laravel Sail 官方维护的 PHP 8.1 运行时目录，并同步更新镜像名以避免缓存混淆：
services:
laravel.test:
build:
context: ./vendor/laravel/sail/runtimes/8.1 # ✅ 必须是此路径，不可自建或写错
dockerfile: Dockerfile
args:
WWWGROUP: '${WWWGROUP}'
image: sail-8.1/app # ✅ 镜像名需匹配版本，防止复用旧镜像
# 其余配置（volumes、ports、environment等）保持不变⚠️ 注意：
立即学习“PHP免费学习笔记（深入）”；
- 不要使用
./docker/8.1或./runtime/8.1等自定义路径——Sail 的构建逻辑依赖vendor/laravel/sail/runtimes/下的标准结构； - 其
Dockerfile内部通过FROM laravelphp/sail-runtime:8.1显式拉取官方预编译镜像，该镜像已验证兼容 PHP 8.1.x CLI 及全部扩展（如mbstring,pdo,xml）。
✅ 第二步：强制重建镜像，清除所有缓存层
Sail 构建高度依赖 Docker 层级缓存。若此前曾用 PHP 8.0 构建过镜像，仅执行 sail build 会复用旧缓存层，导致版本未更新。请务必执行：
# 彻底清除旧镜像、构建缓存及容器卷（确保无残留） ./vendor/bin/sail down -v # 强制无缓存重建（关键！） ./vendor/bin/sail build --no-cache # 启动新环境 ./vendor/bin/sail up -d
? 提示：
--no-cache是解决“明明改了配置却仍运行旧版本”的最有效手段。跳过此步是 90% 用户反复踩坑的主因。
✅ 第三步：验证容器内 PHP 版本是否生效
启动成功后，进入容器终端确认真实运行环境：
./vendor/bin/sail php -v # 正确输出应为： # PHP 8.1.x (cli) (built: XXX) ...
同时可检查 Composer 是否能正常解析依赖：
./vendor/bin/sail composer install -v # 不再报 "Your Composer dependencies require a PHP version >= 8.1.0"
? 补充排查要点
-
检查 Sail 版本兼容性：运行
composer show laravel/sail，确保 ≥v1.22.0（对 PHP 8.1 支持更完善）。若过低，执行composer update laravel/sail升级； -
勿滥用
--ignore-platform-reqs：该参数会跳过 PHP 版本校验，但可能导致运行时语法错误（如match表达式、enum类型在 PHP 8.0 下不可用），仅限临时调试； -
IDE 调试注意：若启用 Xdebug，请确认
SAIL_XDEBUG_MODE=develop,debug且SAIL_XDEBUG_CONFIG未覆盖官方 runtime 的 PHP 8.1 适配配置。
通过以上标准化配置 + 强制重建流程，即可让 Sail 容器精准锁定 PHP 8.1 运行环境，从根源上消除 Composer 依赖冲突报错，保障 Laravel 10+ 项目稳定启动与开发。
