PHP Laravel升级步骤

本文目录导读：

1. 前期准备（非常重要）
2. 升级 Composer 依赖
3. Laravel 11 重大变更处理
4. 其他配置修改
5. 代码兼容性修复
6. 迁移与测试
7. 最终检查清单
8. 小版本升级（如 10.x → 10.y）
9. 注意事项
10. 快速升级脚本（参考）

升级 Laravel 是一个需要谨慎操作的过程，以下是通用的升级步骤，以 Laravel 10 升级到 Laravel 11 为例（其他版本升级逻辑类似）：

---

前期准备（非常重要）

备份代码和数据库

# 备份代码
git checkout -b upgrade-laravel-11
git add .
git commit -m "Before Laravel upgrade"
# 备份数据库
mysqldump -u username -p database_name > backup.sql

确认当前环境要求

Laravel 11 要求：

• PHP >= 8.2
• Composer >= 2.2.0
• 删除对 PHP 8.1 的支持

---

升级 Composer 依赖

修改 composer.json

查看 Laravel 11 的官方要求，更新以下依赖：

{
    "require": {
        "php": "^8.2",
        "laravel/framework": "^11.0",
        "laravel/tinker": "^2.9"
    },
    "require-dev": {
        "fakerphp/faker": "^1.23",
        "laravel/pint": "^1.13",
        "laravel/sail": "^1.26",
        "mockery/mockery": "^1.6",
        "nunomaduro/collision": "^8.0",
        "phpunit/phpunit": "^10.5"
    }
}

更新依赖

# 更新 composer 本身
composer self-update
# 更新依赖（注意：先不要删除旧的依赖）
composer update --with-all-dependencies
# 或者强制更新
composer require laravel/framework:^11.0 --with-all-dependencies

---

Laravel 11 重大变更处理

目录结构变化

Laravel 11 精简了目录结构：

# 删除不再需要的文件
rm -rf app/Http/Middleware  # 中间件移到 app/Http 下
rm -rf app/Console/Kernel.php  # 移除
rm -rf app/Exceptions/Handler.php  # 移除
rm -rf app/Http/Kernel.php  # 移除
# 新增必要的文件
php artisan make:middleware EnsureTokenIsValid  # 重新创建需要的中间件

bootstrap/app.php 完全重写

<?php
use Illuminate\Foundation\Application;
use Illuminate\Foundation\Configuration\Exceptions;
use Illuminate\Foundation\Configuration\Middleware;
return Application::configure(basePath: dirname(__DIR__))
    ->withRouting(
        web: __DIR__.'/../routes/web.php',
        commands: __DIR__.'/../routes/console.php',
        health: '/up',
    )
    ->withMiddleware(function (Middleware $middleware) {
        // 在这里添加你的全局中间件
        // $middleware->append(EnsureTokenIsValid::class);
        // 注册中间件别名
        $middleware->alias([
            'admin' => \App\Http\Middleware\AdminMiddleware::class,
        ]);
    })
    ->withExceptions(function (Exceptions $exceptions) {
        //
    })->create();

移除基础控制器

rm app/Http/Controllers/Controller.php
# 新建 slim 版本的 Contoller
php artisan make:controller BaseController --model=User

---

其他配置修改

环境变量文件

# 检查 .env 文件，添加新配置
PHP_CLI_SERVER_WORKERS=4
CACHE_STORE=file
QUEUE_CONNECTION=database

config/database.php 变化

Laravel 11 默认使用 SQLite，如果你用 MySQL 需要确认配置。

Session 配置

# session 配置简化了
php artisan session:table

---

代码兼容性修复

第三方包兼容性

检查并更新第三方包：

composer outdated  # 查看过期的包

可能需要更新的包：

• laravel/sanctum (^4.0)
• spatie/laravel-permission (^6.0)
• barryvdh/laravel-debugbar (^3.10)

代码修复示例

// 1. 路由模型绑定变化
Route::get('/users/{user}', function (User $user) {
    // 在 Laravel 11 中用法一样，但路由缓存方法变化
});
// 2. 中间件签名变化
public function handle(Request $request, Closure $next): Response
{
    // 返回类型必须为 Response
    return $next($request);
}
// 3. 异常处理
// 在 bootstrap/app.php 中处理
$app->withExceptions(function (Exceptions $exceptions) {
    $exceptions->render(function (AuthenticationException $e, Request $request) {
        if ($request->is('api/*')) {
            return response()->json(['message' => $e->getMessage()], 401);
        }
    });
});

---

迁移与测试

运行迁移和测试

# 数据库迁移（先备份！）
php artisan migrate --pretend  # 查看会执行的 SQL
php artisan migrate
# 清除缓存
php artisan optimize:clear
php artisan config:clear
php artisan route:clear
php artisan view:clear
# 运行测试
php artisan test

性能测试

# 生成路由缓存
php artisan route:cache
php artisan config:cache
php artisan event:cache

---

最终检查清单

• [ ] 所有路由正常工作
• [ ] 所有中间件正常工作
• [ ] API 认证（Sanctum/Passport）正常工作
• [ ] 队列和定时任务正常工作
• [ ] 邮件服务正常
• [ ] 文件上传/存储正常
• [ ] 所有第三方服务（支付、短信等）正常
• [ ] 数据库查询正常，无性能问题
• [ ] 缓存系统正常

---

小版本升级（如 10.x → 10.y）

如果是小版本升级：

composer update laravel/framework
php artisan optimize:clear

---

注意事项

1. 升级前一定要备份
2. 先在本地/测试环境升级，不要直接在生产环境操作
3. 升级过程中保持耐心，可能会遇到多重兼容性问题
4. 查看官方升级指南： Laravel Upgrade Guide

---

快速升级脚本（参考）

#!/bin/bash
# upgrade-laravel.sh
echo "🔍 检查当前版本..."
php artisan --version
echo "📦 备份文件..."
cp composer.json composer.json.bak
cp composer.lock composer.lock.bak
echo "🚀 更新依赖..."
composer require laravel/framework:^11.0 --with-all-dependencies
echo "🛠️ 清除旧缓存..."
php artisan clear-compiled
php artisan optimize:clear
echo "✅ 升级完成！请检查以下内容："
echo "1. 检查 bootstrap/app.php"
echo "2. 检查 .env 文件"
echo "3. 运行 php artisan migrate"
echo "4. 运行 php artisan test"

按照这个流程操作,你的 Laravel 升级会顺利很多，如果遇到具体错误，请提供错误信息，我可以帮你进一步排查。