Linux 下 ThinkPHP 更新操作指南
一 准备与环境检查
- 备份项目与数据库,建议使用 Git 管理代码以便回滚。
- 检查 PHP 版本是否满足目标版本要求:例如 ThinkPHP 8.0 要求 PHP >= 8.0.0;ThinkPHP 6.0 要求 PHP >= 7.1.0;ThinkPHP 5.1 支持 PHP 5.6+。执行命令:
php -v 查看版本。
- 安装或更新 Composer(Linux):
curl -sS https://getcomposer.org/installer | php && sudo mv composer.phar /usr/local/bin/composer,验证:composer --version。
- 如在国内,建议配置 Composer 镜像提升下载速度:
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/。
- 使用 宝塔面板时,需在 PHP 设置中删除禁用的函数(如:putenv、pcntl_signal、proc_open、passthru),否则
php think 相关命令可能失败。
二 标准升级步骤(Composer 方式)
- 进入项目应用根目录(包含 composer.json 的目录),不要进入框架目录执行更新。
- 小版本升级(同主版本内,如 6.0.x → 6.0.y):执行
composer update topthink/framework。
- 指定版本或大版本升级(如 6.1.x → 8.0.x):在
composer.json 的 require 中调整版本约束,例如 "topthink/framework": "^8.0",然后执行 composer update topthink/framework(必要时加 --with-dependencies 同步更新依赖)。
- 更新完成后执行:
php think clear 清理缓存;如使用 OPcache/Redis,一并重启 PHP-FPM 或清理相应缓存。
- 验证版本:
php think version 或 composer show topthink/framework 查看已安装版本。
三 跨大版本升级要点(如 5.x → 6.x 或 6.x → 8.x)
- 阅读目标版本的官方升级指南,按变更说明逐项调整(函数废弃、配置结构、路由规则等)。
- 目录与命名空间变化:如 6.x 起官方推荐应用目录为 app(不少 5.x 项目为 application),升级需按文档迁移;6.0 起必须通过 Composer 安装/更新。
- 配置与环境变量:部分版本将调试开关从
config/app.php 迁移到 .env 的 APP_DEBUG,需同步调整。
- 依赖与扩展:升级后可能需要同步升级 think-orm、think-filesystem 等官方组件,以及第三方扩展,确保与新框架兼容。
- 数据库与数据结构:关注官方变更是否涉及数据迁移或索引/字段调整,先在测试环境验证再上线。
四 常见问题与处理
- 依赖冲突或 PHP 版本不满足:升级 PHP(如至 8.0+)或调整
composer.json 的版本约束;可用 composer why-not topthink/framework 排查冲突包。
- 禁用函数导致命令失败(宝塔常见):在 PHP 管理里删除对 putenv、pcntl_signal、proc_open、passthru 的禁用,重启 PHP-FPM 后再执行
php think。
- 路由 404 或入口异常:生产环境确保 Web 服务器将请求指向 public/ 目录,并配置 URL 重写(Nginx/Apache 伪静态选择 thinkphp 或按官方示例配置)。
- 缓存未生效/页面仍旧:执行
php think clear,并重启 PHP-FPM/OPcache;必要时检查 runtime 目录权限。
- 升级后功能异常:回滚代码(Git),对照官方升级说明逐项修复,先在测试环境验证再上线。