如何在cPanel服务器上升级Laravel版本？是否需重传项目？

在cPanel服务器环境升级Laravel，完全不需要删除整个原有项目后重新上传全量代码。这种全删重传的操作是风险极高的非规范做法，很容易丢失.env环境配置、storage运行日志、用户上传文件、自定义配置，还会造成站点长时间服务中断。

整个流程优先保证可回滚、最短服务中断时间，步骤如下：

• 第一步：前置备份与环境校验
  • 先在cPanel文件管理器将整个项目根目录压缩打包下载到本地，同时通过phpMyAdmin导出对应站点的全量数据库备份，出现任何问题都可以快速回滚到升级前状态。
  • 提前核对目标Laravel版本的系统要求：比如Laravel 11要求PHP 8.2+，在cPanel「MultiPHP Manager」中切换到符合要求的PHP版本，确认安装好fileinfo、mbstring、pdo_mysql、bcmath等必装扩展。
• 第二步：本地完成版本适配（禁止直接在生产服务器改依赖）
  • 拉取生产环境最新代码到本地，对照Laravel官方升级说明调整composer.json中的laravel/framework版本约束，同步调整第三方依赖包的版本，解决所有版本冲突。
  • 本地执行composer update完成依赖更新，对照升级文档列出的破坏性变更逐一修改业务代码，本地全量测试接口、页面、队列、定时任务等所有核心功能，确认无报错。
  • 将升级完成的代码排除.env、storage、node_modules、public目录下的用户上传资源后，打包为升级压缩包。如果cPanel没有SSH权限无法在服务器跑composer，就把本地更新好的vendor目录也打进包，注意本地PHP版本必须和服务器版本完全一致，避免兼容问题。
• 第三步：服务器端升级操作
  • 优先通过SSH连接cPanel服务器（没有SSH就用文件管理器操作），进入项目根目录执行php artisan down将站点切到维护模式，避免访客访问到半升级状态的异常页面。
  • 上传本地打好的升级包到项目根目录的临时文件夹，解压后直接覆盖原有项目的同名文件，不要删除原有项目目录，确保.env配置、storage目录下的文件、用户上传资源完整保留。
  • 执行升级必备命令：

    composer install --no-dev --optimize-autoloader
    php artisan migrate --force
    php artisan config:cache
    php artisan route:cache
    php artisan view:cache
    

    如果升级涉及前端资源变更，提前在本地编译好js、css等静态资源，同步覆盖到public目录对应位置。
  • 确认所有命令执行无报错后，执行php artisan up关闭维护模式，抽查站点核心功能运行正常即可。

只有当原有项目文件被篡改损坏、或者跨超大版本做了全量代码重构（比如从Laravel 5.x直接升级到Laravel 11且业务代码完全重写）时，才考虑全量替换项目文件。哪怕是这种场景，也必须提前备份原有项目的.env文件、storage目录、public下的用户上传资源、数据库，绝对不能直接删除整个项目目录后再上传新代码。

踩坑提示：不要在生产服务器直接执行composer update，这个命令会拉取最新符合约束的包版本，很容易出现未预期的依赖兼容问题，导致站点直接报错。

内容的提问来源于stack exchange，提问作者Tharun Vempati