如何在 cPanel 上逐步安装 Laravel

Laravel is a world-class PHP framework known for its elegant syntax, powerful features, and robust developer ecosystem. However, deploying it on traditional shared hosting or a cPanel environment isn’t as simple as uploading files.

Unlike a one-click install for an app like WordPress, Laravel is a modern framework that relies on a dependency manager (Composer) and has a specific public directory structure for security. A common hurdle for developers is correctly pointing the domain to Laravel’s /public 文件夹。

This guide will walk you through the professional, step-by-step method to install a fresh Laravel application on any cPanel-powered host using Composer and the built-in Terminal.

Steps to install Laravel on cPanel Hosting

Before You Begin: Prerequisites

To follow this guide, you will need:

cPanel Access: Full access to your hosting control panel.
Terminal or SSH Access: Most modern cPanel hosts (like Quape) include a “Terminal” feature. Full SSH access is even better, but the cPanel Terminal is all you need.
Correct PHP Version: Laravel 11 (the current version) requires PHP 8.2 or higher.
Composer: Laravel’s dependency manager. We will check if it’s installed.

Step 1: Set Up Your cPanel Environment

First, we need to ensure your server is ready for Laravel.

1. Set the Correct PHP Version

In your cPanel dashboard, find and click on “Select PHP Version” (it may be called “MultiPHP Manager” on some hosts).
If you are using “MultiPHP Manager,” select your domain from the list and choose PHP 8.2 或者 PHP 8.3 from the dropdown menu, then click “Apply.”
If you are using “Select PHP Version,” set the “Current PHP version” to 8.2 or 8.3.

2. Enable Required PHP Extensions

In the same “Select PHP Version” screen, click on the “Extensions” tab. Laravel requires several extensions to be enabled. Ensure the following are all checked:

dom
fileinfo
mbstring
openssl
pdo_mysql (if you’re using MySQL)
xml
ctype
json

Click “Save” if you make any changes.

Step 2: Access the Terminal and Check for Composer

Now, let’s go to the command line.

In your cPanel dashboard, find and click on the “Terminal” icon (usually under the “Advanced” section). This will open a command-line interface directly in your browser.
To verify Composer is installed and available, type the following command and press Enter:
```
composer -V
```
If you see a version number (e.g., Composer version 2.7.6...), you are ready to proceed! If not, you may need to install Composer manually or ask your hosting provider to enable it. Modern developer-friendly hosts should have it pre-installed.

Step 3: Install Laravel Using Composer

This is where we create the actual project. It’s a security best practice to install Laravel 外部 of your 公共HTML 目录。 This keeps your sensitive files (like .env) from being publicly accessible.

You should already be in your home directory (e.g., /home/your_username). This is the perfect place.
Run the following Composer command to create a new Laravel project. You can replace my_project with your desired application name.
```
composer create-project laravel/laravel my_project
```
Composer will now download Laravel and all its dependencies. This may take a minute or two. Once it’s finished, you will have a new directory named my_project in your home folder.

Step 4: The Critical Step — Point Your Domain to the `/public` Folder

This is the most important part and the one most people get wrong. Your domain needs to point to /home/your_username/my_project/public, not just /home/your_username/public_html.

You have two primary methods to accomplish this. Method 1 is the cleanest and most recommended.

Method 1: The Best Way (Using a Subdomain)

Using a subdomain is the easiest way to control the “Document Root” (the folder the domain loads).

在 cPanel 中，转到 “子域名”.
Create a new subdomain (e.g., app 或者 laravel).
Select the parent domain (e.g., 您的域名.com).
Crucially: 在 “Document Root” field, cPanel will auto-fill something like public_html/app. Delete this and replace it with the exact path to your Laravel project’s public folder:公共HTML (This is wrong!) home/your_username/my_project/public (This is correct!)
Note: cPanel might just show the field editable after public_html/. You may need to click outside the box to edit the full path. If you can’t, use Method 2.
点击 “创造”. Your subdomain app.yourdomain.com now points directly to your Laravel application’s entry point.

Method 2: The Symlink Way (For Your Primary Domain)

If you 必须 use your primary domain (e.g., 您的域名.com) and it’s tied to the 公共HTML folder, this is the best workaround. We will replace the 公共HTML folder with a “symbolic link” (a shortcut) to our project’s public directory.

在 cPanel 中，转到 “File Manager”.
If you have an existing 公共HTML folder, back up any files inside it, then delete the folder.
返回 cPanel Terminal.
Run the following command to create the symbolic link. Make sure to replace your_username 和 my_project with your actual paths.
```
ln -s /home/your_username/my_project/public /home/your_username/public_html
```

This command tells the server, “When someone asks for 公共HTML, just send them to my_project/public instead.”

Step 5: Configure Your Environment (`.env`) File

Your Laravel app needs to connect to a database and know its own URL.

Create a Database: 在 cPanel 中，转到 “MySQL Database Wizard”. Follow the steps to create a new database, a new user, and add that user to the database with “All Privileges.” Note down the database name, username, and password.
Edit the .env 文件：
- In the cPanel 文件管理器, navigate to your project folder (e.g., /home/your_username/my_project).
- You may need to click “Settings” and “Show Hidden Files” to see the .env 文件。
- If you only see .env.example, right-click it and “Copy” it to a new file named .env.
- 右键单击 .env file and select “Edit.”
- 更新 APP_URL to match your subdomain or domain: APP_URL=https://app.yourdomain.com
- 更新 DB_ values with the database, username, and password you just created. 笔记： In cPanel, the database and username are often prefixed (e.g., cpaneluser_mydb, cpaneluser_dbuser).
```
DB_HOST=127.0.0.1
DB_DATABASE=cpaneluser_mydb
DB_USERNAME=cpaneluser_dbuser
DB_PASSWORD=your_strong_password
```
Generate App Key: 在 Terminal, navigate to your project folder (cd my_project) and run:
```
php artisan key:generate
```

Step 6: Run Migrations and Test

You’re all set! Let’s test the database connection and see the site.

在 Terminal, while inside your project directory, run the database migrations:
```
php artisan migrate
```
If it says “Migration successful,” your database connection is working perfectly!
Open your browser and navigate to the subdomain or domain you configured.

You should now see the default Laravel welcome page.

Conclusion: Your Laravel App is Live on cPanel

While deploying Laravel on cPanel involves more steps than a simple upload, it’s a very manageable process. By using Composer in the Terminal and correctly setting your document root, you’ve created a secure, professional, and high-performance setup.

This entire workflow depends on a hosting environment that gives developers the tools they need. A reliable host with SSH/Terminal access, up-to-date PHP versions, and full Git/Composer support is essential. At Quape, our 网站托管 are designed for modern developers, providing the power and flexibility you need to run frameworks like Laravel right out of the box.