Laravel升级兼容性检查_Laravel升级兼容说明【说明】

不是必须但强烈建议运行 php artisan down，因其可避免配置未加载、字段缺失、缓存失效等问题；多服务器需同步执行。

升级前必须运行 php artisan down 吗？

不是必须，但强烈建议。laravel 升级过程常涉及配置变更、迁移文件新增或修改、缓存重建等操作，如果服务持续对外响应，可能出现：

• 配置未加载完成时请求读到旧值或空值
• 新旧模型同时访问同一张表，触发字段缺失错误（如 sqlSTATE[42S22]: column not found）
• 缓存键结构变化导致 Cache::get() 返回 NULL 或反序列化失败

php artisan down 会写入 storage/framework/down 文件并让所有请求返回 503，是成本最低的隔离手段。注意：若使用负载均衡或多服务器部署，需确保所有节点同步执行该命令，否则部分流量仍会打到未下线机器。

composer update 升级时如何锁定 Laravel 版本范围？

直接改 composer.json 中 "laravel/framework" 的版本约束，别依赖默认的 ^10.0 这类宽泛写法。例如从 9.x 升 10.x，应明确写成：

"laravel/framework": "10.48.12"

理由：Laravel 的小版本更新（如 10.47 → 10.48）可能包含不兼容的底层变更（比如 IlluminateSupportStr::of() 返回对象行为微调），而 ^10.0 会让 Composer 自动拉取最新补丁版，容易在 CI 或不同环境产生行为差异。

常见踩坑点：

• 本地用 composer update laravel/framework 但没加 --with-all-dependencies，导致 symfony/* 等依赖版本滞后，引发 ArgumentCountError
• 忘记检查 phpunit/phpunit 是否与新版 Laravel 兼容（Laravel 10 要求 PHPUnit ≥ 10.0）
• composer.lock 没提交，团队成员 composer install 时拉到不同版本

升级后 php artisan migrate 报错：table doesn’t exist 或 Column already exists

这不是数据库问题，而是迁移文件和当前 schema 状态不一致导致的。Laravel 不会自动跳过已执行过的迁移，也不会校验表结构是否匹配代码定义。

典型场景：

• 你本地开发时手动改过数据库字段（比如加了 is_active），但没写对应迁移
• 生产环境之前跳过了某次迁移，现在补跑时发现表已存在或字段重复

解决步骤：

• 先运行 php artisan migrate:status 查看哪些迁移标为 Ran，哪些是 Pending
• 对于「已存在但未标记为已执行」的迁移，用 php artisan migrate --pretend 看它实际要执行什么 SQL，确认无害后再加 --force
• 若确定某迁移已手工完成，可用 php artisan db:table 验证结构，再用 php artisan migrate:mark --step=1 手动标记为已执行

注意：不要直接删 migrations 表里的记录，Laravel 10+ 的迁移解析器对顺序更敏感，错位会导致后续全部失败。

升级到 Laravel 10 后，config/app.php 的 timezone 和 locale 还能直接改吗？

能改，但要注意两点影响：

• timezone 影响 carbon 实例默认时区，如果应用里大量用 now() 或 Carbon::parse() 且没显式传时区，升级后可能发现日志时间、缓存过期时间、队列延迟都偏移 8 小时（尤其部署在 UTC 服务器上）
• locale 控制 Lang 加载路径和 trans() 行为，Laravel 10 默认启用 fallback_locale 强制回退逻辑，如果旧项目没配 fallback_locale，升级后部分翻译可能突然变成英文而非空字符串

建议做法：

• 把 APP_TIMEZONE 和 APP_LOCALE 移到 .env，避免硬编码在 config 里
• 检查所有 Carbon::now() 调用，显式指定时区：Carbon::now('Asia/Shanghai')
• 运行 php artisan lang:publish 确认语言包路径是否仍为 resources/lang/zh-CN，Laravel 10 默认只认 zh_CN 下划线格式

升级本身不难，难的是那些没写进文档的隐式依赖——比如某个第三方包悄悄依赖了 Laravel 9 的 IlluminateFoundationApplication 内部方法，一升级就报 Call to undefined method。这类问题只能靠 composer why-not laravel/framework:10.* 逐个排查，别指望一次全通。