首次通过cPanel在子域名部署Laravel 5.5遇HTTP ERROR 500，求部署指引

Hey there, sorry to hear you're stuck with that HTTP 500 error while setting up your Laravel 5.5 app on a subdomain—let's break down the exact steps to get this working, without messing up your existing Joomla site on the main domain.

Step 1: Create & Configure the Subdomain in cPanel #

First, let's set up the subdomain correctly:

• Log into your cPanel account and locate the Subdomains tool (usually under the "Domains" section).
• Enter your subdomain prefix (e.g., if you want laravel.yourdomain.com, type laravel in the "Subdomain" field).
• For the "Document Root" field, don't just use the default—set it to point directly to Laravel's public folder. For example, if you plan to store your Laravel project in public_html/laravel-app, set the document root to public_html/laravel-app/public. This is critical because Laravel's entry point is the index.php in the public folder.
• Click Create to finalize the subdomain setup.

Step 2: Upload Your Laravel 5.5 Files #

Next, get your Laravel code onto the server:

• You can use FTP (like FileZilla) to upload a zipped copy of your Laravel project, then unzip it directly in the public_html/laravel-app directory (matching the parent folder of your document root from Step 1).
• Alternatively, if your code is hosted on Git, use cPanel's Git Version Control tool to clone your repository into the same public_html/laravel-app directory.

Step 3: Configure the .env File #

Laravel relies heavily on the .env file for configuration—let's set this up:

• If you don't have a .env file, make a copy of the .env.example file and rename it to .env.
• Open .env and update these key values:
  • APP_URL: Set this to your full subdomain URL, e.g., APP_URL=https://laravel.yourdomain.com
  • Database credentials: Fill in DB_HOST, DB_DATABASE, DB_USERNAME, DB_PASSWORD with your cPanel database details (create a new database/user for Laravel if you haven't already).
• Generate your application key (required for Laravel to run):
  • Open cPanel's Terminal tool, navigate to your Laravel project root with cd public_html/laravel-app, then run:

    php artisan key:generate
    

  • This will automatically populate the APP_KEY field in your .env file.

Step 4: Fix File Permissions #

Incorrect permissions are a super common cause of 500 errors in Laravel:

• From the same Terminal window (project root), run these commands to give Laravel write access to critical directories:

  chmod -R 755 storage bootstrap/cache
  chown -R your-cpanel-username:your-cpanel-username storage bootstrap/cache
  

  Replace your-cpanel-username with your actual cPanel username (you can find this at the top-right corner of your cPanel dashboard).

Step 5: Verify the .htaccess File #

Make sure the .htaccess file in your subdomain's public directory is the default Laravel one—this handles URL routing correctly:

• The file should look like this:

  <IfModule mod_rewrite.c>
      <IfModule mod_negotiation.c>
          Options -MultiViews -Indexes
      </IfModule>
  
      RewriteEngine On
  
      # Handle Authorization Header
      RewriteCond %{HTTP:Authorization} .
      RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]
  
      # Redirect Trailing Slashes If Not A Folder...
      RewriteCond %{REQUEST_FILENAME} !-d
      RewriteCond %{REQUEST_URI} (.+)/$
      RewriteRule ^ %1 [L,R=301]
  
      # Send Requests To Front Controller...
      RewriteCond %{REQUEST_FILENAME} !-d
      RewriteCond %{REQUEST_FILENAME} !-f
      RewriteRule ^ index.php [L]
  </IfModule>
  

• If it's missing or modified, replace it with the above code.

Step 6: Check PHP Version Compatibility #

Laravel 5.5 requires PHP 7.0.0 or higher (but doesn't support PHP 8.x). Since your main domain runs Joomla (which might use a different PHP version), you can set a separate version for your subdomain:

• Go to cPanel's MultiPHP Manager tool.
• Find your subdomain in the list, check the box next to it, then select a PHP version between 7.0 and 7.4 from the dropdown.
• Click Apply to save the change.

Step 7: Diagnose the Exact 500 Error (If Still Stuck) #

If you're still seeing the 500 error, cPanel's error logs will tell you exactly what's wrong:

• Open the Error Logs tool in cPanel.
• Look for entries related to your subdomain—common issues here might include:
  • Missing application key
  • Database connection failures
  • Permission issues on storage or bootstrap/cache
  • Outdated PHP extensions (Laravel 5.5 requires extensions like mbstring, openssl, PDO—enable these in cPanel's Select PHP Version tool if missing)

Key Note to Avoid Joomla Conflicts #

Since your main domain runs Joomla, as long as your Laravel project's files are stored in a separate directory (like public_html/laravel-app) and the subdomain's document root doesn't overlap with Joomla's files (usually public_html), there's no risk of conflict. The subdomain will act as a completely separate site.

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