Laravel Sail 升级 PHP 版本至 8.1 的完整配置指南-php教程-PHP中文网

Laravel Sail 升级 PHP 版本至 8.1 的完整配置指南

本文详解如何在 Laravel Sail 环境中正确升级 PHP 版本至 8.1+，解决 Your Composer dependencies require a PHP version ">= 8.1.0". You are running 8.0.14 错误——该错误源于 Sail 容器内运行的 PHP 版本与宿主机不一致，需同步更新 Docker 构建配置。

本文详解如何在 laravel sail 环境中正确升级 php 版本至 8.1+，解决 `your composer dependencies require a php version ">= 8.1.0". you are running 8.0.14` 错误——该错误源于 sail 容器内运行的 php 版本与宿主机不一致，需同步更新 docker 构建配置。

Laravel Sail 是 Laravel 官方提供的轻量级 Docker 开发环境封装工具，其核心特点是容器化隔离：你本地系统（如 WSL 中通过 apt 安装并切换的 PHP 8.1）仅影响宿主机 CLI，而 Sail 启动的服务（包括 php, composer, artisan）全部运行在独立的 Docker 容器中。因此，即使 php -v 显示 8.1.8，Sail 仍可能使用默认的 PHP 8.0 运行时——这正是报错中 “You are running 8.0.14” 的真实来源。

✅ 正确解决方案：切换 Sail 运行时为 PHP 8.1

Laravel Sail 自 v1.15.0 起支持多 PHP 版本运行时，官方已预置 runtimes/8.1 目录。你需要显式指定使用该版本：

修改 docker-compose.yml
找到 services.app.build 部分，将 context 和 image 更新为 PHP 8.1 对应路径：

services:
  app:
    build:
      context: ./vendor/laravel/sail/runtimes/8.1  # ← 关键：指向 8.1 运行时
      dockerfile: Dockerfile
      args:
        WWWGROUP: '${WWWGROUP}'
    image: sail-8.1/app  # ← 关键：镜像标签需匹配

重建容器镜像
运行以下命令强制重建（--no-cache 确保不复用旧层）：
```
./vendor/bin/sail build --no-cache
```
重启服务
```
./vendor/bin/sail up -d
```

验证容器内 PHP 版本
进入容器确认生效：

./vendor/bin/sail php -v
# 输出应为：PHP 8.1.x (cli) (built: ...)

⚠️ 注意事项与常见误区

不要修改 composer.json 的 platform 配置来绕过校验：如 "php": "8.0.14"，这会掩盖根本问题，且可能导致运行时兼容性故障（如 PHP 8.1 新语法或扩展缺失）。
确保 Sail 版本 ≥ v1.15.0：旧版 Sail 不含 runtimes/8.1。升级 Sail：
```
composer require laravel/sail:"^1.15" --dev
php artisan sail:install
```
WSL 用户无需在宿主机卸载 PHP 8.0：Sail 容器完全独立，宿主机 PHP 版本仅影响 sail 脚本本身（该脚本是 Shell 脚本，不依赖 PHP），因此保留多个 PHP 版本无害。
若 runtimes/8.1 目录不存在：请检查 vendor/laravel/sail/ 是否完整；可尝试 composer update laravel/sail --with-all-dependencies 强制刷新。