必须全量备份项目文件与数据库，修改composer.json中laravel/framework版本号，运行composer update --with-all-dependencies，清空各类缓存，执行php artisan migrate --force（生产环境不可省略），并准备文件与数据库双回滚方案。
升级 Laravel 框架前必须确保现有数据库结构、配置文件与业务数据可完整还原，避免因框架版本不兼容导致迁移失败、Eloquent 行为变更或路由解析异常引发线上服务中断。
升级前全量备份项目文件与数据库
进入项目根目录，执行 tar 命令打包全部源码（含 vendor、.env、storage 和 bootstrap/cache）：
sudo tar -czvf laravel-pre-upgrade-$(date +%Y%m%d_%H%M%S).tar.gz /var/www/html/myapp
同步导出当前数据库快照，强制使用 UTF8MB4 字符集防止 emoji 或四字节字符乱码：
mysqldump --default-character-set=utf8mb4 -u $DB_USER -p$DB_PASS $DB_NAME > laravel-db-pre-upgrade-$(date +%Y%m%d_%H%M%S).sql
【必须确认 .env 文件未被排除在压缩包外】。若使用 --exclude 参数，请显式保留 .env，否则恢复后将丢失数据库连接、APP_KEY 等关键配置。
验证备份完整性
检查 tar 包是否包含 storage/app、bootstrap/cache 和 config/ 目录：
tar -tzf laravel-pre-upgrade-*.tar.gz | grep -E '^(storage/app|bootstrap/cache|config/)' | head -n 3
用 mysqlcheck 工具验证 SQL 文件可解析性（不实际导入）：
mysql -u $DB_USER -p$DB_PASS -e "SELECT 1" $DB_NAME && echo "连接正常" || echo "数据库凭证错误"
对 SQL 文件执行轻量语法校验：
head -n 50 laravel-db-pre-upgrade-*.sql | grep -q "CREATE TABLE" && echo "SQL 头部有效" || echo "SQL 文件可能为空或损坏"
执行 Laravel 版本升级
第一步：修改 composer.json 中 laravel/framework 行版本号，例如从 "10.48.12" 升至 "11.9.0"；
第二步：运行 composer update --with-all-dependencies，该参数确保子依赖版本同步适配新框架；
第三步：清空所有缓存并重新生成：
php artisan config:clear → php artisan cache:clear → php artisan view:clear → php artisan route:clear → php artisan event:clear
第四步：执行迁移（仅当升级涉及结构变更时）：
php artisan migrate --force
【禁止在生产环境跳过 --force 参数】。Laravel 11 默认禁用非本地环境的 migrate 命令，漏加此参数会导致命令静默退出且无提示。
回滚到旧版本的三步操作
方法一：文件系统级快速回滚
停止 PHP-FPM 或 Apache 服务 → 删除当前项目目录 → 解压备份 tar 包到原路径 → 重置 storage 权限：
sudo chown -R www-data:www-data storage/ && sudo chmod -R 775 storage/
方法二：数据库级精准回滚
先删除升级后新建的迁移记录（防止 migrate:reset 误删原始表）：
mysql -u $DB_USER -p$DB_PASS $DB_NAME -e "DELETE FROM migrations WHERE batch > (SELECT MAX(batch) FROM (SELECT * FROM migrations) AS tmp WHERE migration LIKE '%2026_08%');"
再导入原始 SQL 文件：
mysql -u $DB_USER -p$DB_PASS $DB_NAME
方法三：Composer 版本锁定回退
将 composer.json 中 laravel/framework 版本改回原值 → 执行 composer install --no-dev --optimize-autoloader → 清空 bootstrap/cache/compiled.php（如存在）。
