如何通过GitHub Actions部署Laravel到cPanel？部署报错求助

错误原因分析及解决方案 #

1. 检查PHP版本兼容性 #

Laravel各版本对PHP有明确的最低版本要求，比如：

• Laravel 8：PHP 7.3+
• Laravel 9：PHP 8.0+
• Laravel 10：PHP 8.1+
• Laravel 11：PHP 8.2+

操作步骤：

• 登录cPanel，找到Select PHP Version工具
• 确认当前PHP版本是否匹配你的Laravel项目要求，不匹配则切换到对应版本

2. 检查ini_set函数是否被禁用 #

Call to undefined function ini_set()最常见的原因是该函数被服务器的PHP配置禁用：

• 进入cPanel的Select PHP Version，点击Options标签
• 找到disable_functions选项，查看其中是否包含ini_set
• 如果有，将ini_set从禁用列表中移除，保存更改

3. 确保vendor目录完整性 #

手动上传vendor目录容易出现文件损坏或环境不兼容问题：

• 如果服务器支持SSH连接，登录后进入项目目录，执行：

  composer install --no-dev --optimize-autoloader
  

• 若无法使用SSH，建议删除服务器上的vendor目录，重新在本地执行composer install，然后用压缩包（zip）完整打包vendor目录，上传到服务器后解压，避免分文件上传导致的遗漏

部署流程优化建议 #

1. 重构GitHub Actions工作流 #

当前工作流排除了public和vendor，依赖手动上传，容易出错。建议在Actions中完成依赖安装和前端构建，自动同步所有必要文件：

on:
  push:
    branches: [ main ]
name: 🚀 Deploy to cPanel
jobs:
  web-deploy:
    name: 🎉 Deploy
    runs-on: ubuntu-latest
    steps:
    - name: 🚚 Get latest code
      uses: actions/checkout@v4

    - name: 🛠️ Setup PHP
      uses: shivammathur/setup-php@v2
      with:
        php-version: '8.1' # 替换为你的Laravel要求的PHP版本
        extensions: mbstring, dom, fileinfo, mysqlnd
        coverage: none

    - name: 📦 Install Composer dependencies
      run: composer install --no-dev --optimize-autoloader --no-interaction --no-progress

    - name: 🎨 Setup Node.js
      uses: actions/setup-node@v4
      with:
        node-version: '18' # 替换为项目兼容的Node版本
        cache: 'npm'

    - name: 📦 Install npm dependencies & build assets
      run: |
        npm install
        npm run build

    - name: 📂 Sync files to cPanel
      uses: SamKirkland/FTP-Deploy-Action@4.2.0
      with:
        server: ${{ secrets.FTP_SERVER }}
        username: ${{ secrets.FTP_USERNAME }}
        password: ${{ secrets.FTP_PASSWORD }}
        exclude: |
          **/.git*
          **/.git*/**
          **/node_modules/**
          .env

2. 调整cPanel目录结构（安全最佳实践） #

默认cPanel网站根目录是public_html，建议将Laravel项目的核心文件放在public_html之外，仅将public目录的内容放入public_html：

1. 在cPanel文件管理器中，在public_html同级目录创建新文件夹（如laravel_project）
2. 将Laravel项目除public外的所有文件上传到laravel_project
3. 将public目录中的所有文件移动到public_html
4. 修改public_html/index.php中的路径：

   // 原路径
   require __DIR__.'/../vendor/autoload.php';
   $app = require_once __DIR__.'/../bootstrap/app.php';
   // 修改为
   require __DIR__.'/../laravel_project/vendor/autoload.php';
   $app = require_once __DIR__.'/../laravel_project/bootstrap/app.php';
   

3. 环境变量配置 #

• 不要上传本地的.env文件，在服务器的laravel_project目录中新建.env文件
• 配置正确的APP_URL、DB_*（数据库连接）、CACHE_DRIVER等参数
• 执行php artisan config:cache（SSH可用时）或手动清理缓存，确保配置生效

4. 权限设置 #

确保Laravel需要写入的目录有正确权限：

• 如果使用SSH，执行：

  chmod -R 755 storage bootstrap/cache
  chown -R your_cpanel_username:your_cpanel_username storage bootstrap/cache
  

• 若无法使用SSH，在cPanel文件管理器中选中storage和bootstrap/cache目录，设置权限为755

专业技巧 #

• 优先使用SSH而非FTP：SSH传输更稳定，支持执行命令，便于自动化部署和问题排查
• 启用版本控制的环境配置：可以用.env.example作为模板，确保服务器环境配置与本地一致
• 定期清理缓存：部署后执行php artisan cache:clear、php artisan config:cache、php artisan route:cache优化性能
• 开启错误日志：在.env中设置APP_DEBUG=false，LOG_CHANNEL=stack，查看storage/logs目录下的日志文件，便于定位隐藏问题

内容的提问来源于stack exchange，提问作者Noor ul islam