Laravel 13 升级指南

摘要

Laravel 13 的升级过程相对平滑，破坏性变更极少。本文将提供详细的升级指南，包括：

  • 升级前准备工作
  • 依赖更新步骤
  • 破坏性变更详解
  • 新特性迁移策略
  • 测试与验证
  • 常见问题解决

本文适合计划升级到 Laravel 13 的开发者。

1. 升级概览

1.1 升级难度评估

项目难度
从 Laravel 12 升级低
从 Laravel 11 升级中等
从 Laravel 10 升级较高

1.2 升级时间估算

项目规模预计时间
小型项目1-2 小时
中型项目半天
大型项目1-2 天

1.3 PHP 版本要求

Laravel 13 要求 PHP 8.3 或更高版本。

2. 升级前准备

2.1 检查 PHP 版本

1
2
php -v
# 确保版本 >= 8.3

2.2 备份项目

1
2
3
4
5
6
7
# 备份数据库
php artisan db:backup

# 备份代码
git checkout -b upgrade-laravel-13
git add .
git commit -m "Backup before Laravel 13 upgrade"

2.3 检查依赖兼容性

1
2
# 检查第三方包兼容性
composer outdated

3. 升级步骤

3.1 更新 composer.json

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
    "require": {
        "php": "^8.3",
        "laravel/framework": "^13.0"
    },
    "require-dev": {
        "laravel/pint": "^1.13",
        "laravel/sail": "^1.26",
        "mockery/mockery": "^1.6",
        "nunomaduro/collision": "^8.1",
        "phpunit/phpunit": "^11.0",
        "spatie/laravel-ignition": "^2.4"
    }
}

3.2 运行 Composer 更新

1
composer update laravel/framework

3.3 更新配置文件

1
2
# 发布新的配置文件
php artisan config:publish

3.4 清除缓存

1
2
3
4
5
php artisan clear-compiled
php artisan cache:clear
php artisan config:clear
php artisan route:clear
php artisan view:clear

4. 破坏性变更

4.1 PHP 版本要求

1
2
// 确保使用 PHP 8.3+ 特性
// 如：类型化属性、枚举、只读属性等

4.2 已移除的方法

1
2
// 检查是否使用了已移除的方法
// 大多数方法只是弃用，未移除

4.3 配置变更

1
2
// config/app.php
// 检查新配置项

5. 新特性迁移

5.1 启用 PHP Attributes

1
2
3
4
5
6
7
8
9
10
// 将传统路由定义迁移到属性
// 传统方式
Route::get('/users', [UserController::class, 'index']);

// 新方式（可选）
class UserController
{
    #[Get('/users')]
    public function index() {}
}

5.2 使用 Laravel AI SDK

1
2
# 安装 AI SDK
composer require laravel/ai
1
2
// 配置
php artisan vendor:publish --tag=laravel-ai-config

5.3 启用 JSON:API Resources

1
2
3
4
5
6
7
// 更新资源类
use Illuminate\Http\Resources\Json\JsonApiResource;

class PostResource extends JsonApiResource
{
    // ...
}

6. 测试验证

6.1 运行测试套件

1
php artisan test

6.2 检查静态分析

1
./vendor/bin/phpstan analyse

6.3 检查代码风格

1
./vendor/bin/pint --test

6.4 功能测试清单

  • 用户认证
  • API 端点
  • 队列任务
  • 定时任务
  • 文件上传
  • 邮件发送
  • 缓存功能

7. 常见问题

7.1 依赖冲突

1
2
# 解决依赖冲突
composer update --with-dependencies

7.2 配置缓存问题

1
2
# 清除所有缓存
php artisan optimize:clear

7.3 第三方包不兼容

1
2
3
4
# 检查包是否有 Laravel 13 兼容版本
composer show | grep laravel

# 等待或提交 PR

8. 升级后优化

8.1 启用 OPcache

1
2
3
// config/opcache.php
'enable' => true,
'validate_timestamps' => false,

8.2 配置队列

1
2
// 使用新的队列路由
Queue::route(ProcessPodcast::class, queue: 'podcasts');

8.3 启用新安全特性

1
// 添加 PreventRequestForgery 中间件

9. 回滚计划

9.1 准备回滚

1
2
3
# 保留旧版本分支
git checkout main
git branch backup-laravel-12

9.2 回滚步骤

1
2
3
4
5
6
7
8
# 恢复 composer.json
git checkout main -- composer.json composer.lock

# 重新安装依赖
composer install

# 清除缓存
php artisan optimize:clear

10. 总结

Laravel 13 的升级过程相对简单：

  1. 准备充分：备份、检查依赖
  2. 逐步升级：更新依赖、配置
  3. 全面测试：运行测试套件
  4. 渐进迁移：逐步采用新特性

通过本指南，您可以平滑地将应用升级到 Laravel 13。

参考资料