本文详解如何解决 laravel sail 启动时报错 “your composer dependencies require a php version >= 8.1.0. you are running 8.0.14” 的根本原因——该错误并非本地 cli php 版本问题，而是 sail 容器内运行时 php 版本未同步升级所致。
本文详解如何解决 laravel sail 启动时报错 “your composer dependencies require a php version >= 8.1.0. you are running 8.0.14” 的根本原因——该错误并非本地 cli php 版本问题，而是 sail 容器内运行时 php 版本未同步升级所致。
你执行 php -v 看到的是 宿主机（WSL）的 PHP 8.1.8，完全正确；但 sail up 启动的是 Docker 容器环境，其 PHP 版本由 docker-compose.yml 中定义的构建上下文（build.context）和底层镜像决定——与你的 WSL 系统 PHP 无关。报错中 “You are running 8.0.14” 指的就是容器内实际运行的 PHP 版本，说明当前 Sail 服务仍基于 PHP 8.0 运行时构建。
✅ 正确配置：强制切换至 PHP 8.1 运行时
打开项目根目录下的 docker-compose.yml，定位 laravel.test 服务，将 build.context 和 image 明确指向 Laravel 官方维护的 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 等）保持不变
⚠️ 关键提醒：
- 不要使用自建的
./docker/8.1目录或复制修改过的 Dockerfile —— Sail 构建逻辑强依赖vendor/laravel/sail/runtimes/下的官方结构； - 官方
8.1/Dockerfile内部通过FROM laravelphp/sail-runtime:8.1拉取经 Laravel 团队验证的纯净 PHP 8.1 基础镜像，确保版本准确、扩展完整、Xdebug 兼容。
? 强制重建镜像（清除所有缓存）
仅修改 docker-compose.yml 不足以生效！Docker 默认复用历史构建层，旧的 PHP 8.0 镜像可能被缓存复用。必须执行强制无缓存重建：
# 彻底清除旧镜像、构建缓存及残留容器卷 ./vendor/bin/sail down -v ./vendor/bin/sail build --no-cache # 重新启动（-d 后台运行） ./vendor/bin/sail up -d
? 提示：
--no-cache是关键参数，它禁用所有 Docker 层级缓存，确保从sail-runtime:8.1重新拉取并完整构建。
✅ 验证是否生效
执行以下命令检查容器内真实 PHP 版本：
./vendor/bin/sail php -v
预期输出应为：
PHP 8.1.x (cli) (built: ...)
同时可进入容器验证 Composer 是否正常解析依赖：
./vendor/bin/sail composer install -v
若不再报 Your Composer dependencies require a PHP version ">= 8.1.0"，即表示修复成功。
⚠️ 补充注意事项
-
Sail 版本兼容性：运行
composer show laravel/sail，确保 ≥ v1.20.0（对 PHP 8.1 支持更稳定）。如过低，请升级：composer update laravel/sail
避免
.env干扰：Sail 不读取SAIL_PHP_VERSION=8.1等自定义变量，仅依赖docker-compose.yml配置，无需在.env中添加相关设置。IDE 调试适配：若启用 Xdebug，确认
SAIL_XDEBUG_MODE=develop,debug且SAIL_XDEBUG_CONFIG未覆盖官方 runtime 预设——官方8.1运行时已内置适配 PHP 8.1 的 Xdebug 3 配置。Composer 依赖同步：确保
composer.json中require.php字段为"php": "^8.1"，并与 Laravel 10+ 要求一致；否则即使容器 PHP 升级成功，composer install仍可能因平台约束失败。
通过以上标准化配置与强制重建流程，即可精准锁定容器内 PHP 8.1 运行环境，彻底解决因版本错配导致的依赖解析失败、Artisan 命令崩溃及应用启动异常等问题。
php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
