لاراول یکی از فریم‌ورک‌های محبوب PHP برای توسعه وب‌سایت‌ها و برنامه‌های تحت وب است. پس از تکمیل پروژه، یکی از مراحل مهم، انتقال آن از محیط توسعه به هاست و آماده‌سازی برای استفاده کاربران است.
اگر برای میزبانی سایت خود از هاست مجهز به cPanel استفاده می‌کنید، ممکن است این سؤال برایتان پیش بیاید که چگونه می‌توان Laravel را روی هاست اشتراکی اجرا کرد و چه تنظیماتی برای راه‌اندازی آن لازم است.
در این مقاله، مراحل نصب و استقرار پروژه Laravel روی cPanel را بررسی می‌کنیم؛ از انتخاب نسخه PHP و آماده‌سازی فایل‌ها تا تنظیم پایگاه داده، پیکربندی فایل .env و رفع خطاهای رایج.
آیا می‌توان Laravel را روی هاست اشتراکی نصب کرد؟
بله، بسیاری از پروژه‌های Laravel را می‌توان روی هاست اشتراکی اجرا کرد؛ البته به شرطی که امکانات هاست با نیازمندی‌های پروژه سازگار باشد.
پیش از خرید یا استفاده از هاست، موارد زیر را بررسی کنید:
- نسخه PHP موردنیاز پروژه
- امکان فعال‌سازی افزونه‌های PHP موردنیاز
- دسترسی به Composer یا امکان نصب وابستگی‌ها در محیط دیگری
- امکان ایجاد پایگاه داده و کاربر MySQL
- امکان تنظیم Document Root دامنه
- محدودیت‌های حافظه، زمان اجرا و فضای ذخیره‌سازی
- دسترسی به Cron Job در صورت نیاز پروژه
- امکان اجرای Queue Worker یا استفاده از راهکار جایگزین، اگر پروژه به آن نیاز دارد
بعضی از قابلیت‌های موردنیاز پروژه‌های بزرگ، مانند اجرای دائمی فرایندها، ممکن است در هاست اشتراکی در دسترس نباشند. در این شرایط، استفاده از VPS یا سرور اختصاصی می‌تواند انتخاب مناسب‌تری باشد.
مرحله اول: بررسی نسخه PHP در cPanel
ابتدا وارد پنل cPanel هاست خود شوید.
بسته به نسخه cPanel و تنظیمات شرکت میزبانی، بخشی با عنوان‌هایی مانند Select PHP Version، MultiPHP Manager یا MultiPHP INI Editor در دسترس خواهد بود.
نسخه PHP را مطابق نیازمندی‌های پروژه Laravel انتخاب کنید.
برای مثال، اگر پروژه با PHP 8.3 سازگار است، باید نسخه PHP مناسب را برای دامنه خود فعال کنید. نسخه موردنیاز را حدس نزنید؛ فایل composer.json و مستندات نسخه Laravel را بررسی کنید.
همچنین مطمئن شوید افزونه‌های PHP موردنیاز پروژه فعال هستند. این افزونه‌ها بسته به پروژه ممکن است شامل موارد زیر باشند:
mbstringopensslpdo_mysqltokenizerxmlctypejsoncurlfileinfobcmathzip
فهرست بالا نمونه‌ای از افزونه‌های متداول است و نیازمندی‌های دقیق به نسخه PHP و وابستگی‌های پروژه بستگی دارند.
مرحله دوم: آماده‌سازی پروژه Laravel برای انتقال
پیش از انتقال پروژه به هاست، باید وابستگی‌ها و فایل‌های موردنیاز آن را آماده کنید.
در سیستم توسعه، وارد پوشه پروژه شوید و دستور زیر را اجرا کنید:
composer install --no-dev --optimize-autoloader
این دستور وابستگی‌های ثبت‌شده در composer.lock را نصب می‌کند و بسته‌های توسعه‌ای را کنار می‌گذارد.
اگر پروژه از Vite برای مدیریت فایل‌های CSS و JavaScript استفاده می‌کند، فایل‌های فرانت‌اند را نیز بسازید:
npm ci
npm run build
این دستورات باید در محیطی اجرا شوند که Node.js و npm مناسب پروژه نصب شده باشند.
پس از Build، مطمئن شوید فایل‌های تولیدشده، از جمله فایل‌های موردنیاز داخل public/build، همراه پروژه منتقل می‌شوند.
نکته: فایل .env سیستم توسعه را بدون بررسی روی هاست قرار ندهید. تنظیمات محیط Production باید جداگانه و با اطلاعات واقعی سرور تکمیل شوند.
مرحله سوم: انتقال فایل‌های پروژه به هاست
برای انتقال پروژه می‌توانید از File Manager داخل cPanel، ابزار SFTP یا Git استفاده کنید؛ البته دسترسی‌های موجود در هر هاست متفاوت است.
در بسیاری از هاست‌ها، مسیر public_html به‌عنوان پوشه عمومی دامنه اصلی استفاده می‌شود. فایل‌های اصلی Laravel، مانند app، vendor، storage و bootstrap، نباید مستقیماً در معرض دسترسی وب قرار بگیرند.
یک ساختار پیشنهادی به شکل زیر است:
/home/USERNAME/
├── laravel-app/
│ ├── app/
│ ├── bootstrap/
│ ├── config/
│ ├── public/
│ ├── resources/
│ ├── routes/
│ ├── storage/
│ ├── vendor/
│ ├── artisan
│ ├── composer.json
│ └── .env
└── public_html/
در این مثال، فایل‌های اصلی پروژه در پوشه‌ای خارج از public_html قرار می‌گیرند و فایل‌های عمومی از مسیر laravel-app/public ارائه می‌شوند.
USERNAME را با نام کاربری واقعی هاست جایگزین کنید.
این ساختار یک پیشنهاد عمومی است؛ مسیر واقعی پوشه خانگی و امکان تغییر Document Root به تنظیمات هاست بستگی دارد.
مرحله چهارم: تنظیم Document Root دامنه
مهم‌ترین نکته امنیتی هنگام اجرای Laravel روی هاست این است که ریشه وب‌سرور باید پوشه public پروژه باشد.
در cPanel ممکن است بتوانید Document Root دامنه اصلی یا یک دامنه فرعی را از بخش‌هایی مانند Domains تنظیم کنید. امکانات این بخش به نسخه cPanel و سیاست شرکت میزبانی بستگی دارد.
برای مثال، اگر پروژه در مسیر زیر قرار دارد:
/home/USERNAME/laravel-app
مسیر عمومی موردنظر باید چنین باشد:
/home/USERNAME/laravel-app/public
در این حالت، وب‌سرور فایل‌های عمومی را از پوشه public ارائه می‌کند و فایل‌هایی مانند .env و composer.json در ریشه عمومی وب قرار نمی‌گیرند.
اگر امکان تغییر Document Root وجود نداشته باشد چه کنیم؟
اگر هاست اجازه تنظیم Document Root را نمی‌دهد، دو راهکار رایج وجود دارد:
- از پشتیبانی هاست بخواهید Document Root دامنه را به پوشه
publicپروژه تغییر دهد. - در صورت امکان و با رعایت ساختار امن، فایل‌های عمومی را در
public_htmlقرار دهید و مسیرهای لازم را به پوشه اصلی پروژه متصل کنید.
روش دوم نیازمند دقت بیشتری است؛ نباید کل پروژه Laravel را داخل public_html کپی کنید یا با تغییر ساده مسیرها، فایل‌های حساس را در معرض وب قرار دهید.
از راهکارهای مبتنی بر انتقال فایل‌ها یا ساخت لینک نمادین فقط زمانی استفاده کنید که محدودیت‌های دسترسی و پیکربندی وب‌سرور را به‌خوبی می‌شناسید.
مرحله پنجم: ساخت پایگاه داده در cPanel
اگر پروژه از MySQL استفاده می‌کند، باید پایگاه داده و کاربر آن را ایجاد کنید.
در cPanel معمولاً بخشی با عنوان MySQL Databases یا Database Wizard برای این کار وجود دارد.
مراحل کلی عبارت‌اند از:
- یک پایگاه داده جدید ایجاد کنید.
- یک کاربر پایگاه داده با رمز عبور امن بسازید.
- کاربر را به پایگاه داده متصل کنید.
- مجوزهای موردنیاز را به کاربر بدهید.
در بسیاری از هاست‌ها، نام پایگاه داده و نام کاربر با پیشوند حساب هاست ساخته می‌شوند. برای مثال، نام واقعی ممکن است به شکل account_example باشد، نه صرفاً example.
اطلاعات نهایی را یادداشت کنید تا در مرحله بعد در فایل .env قرار دهید.
مرحله ششم: تنظیم فایل .env
فایل .env تنظیمات محیط اجرای Laravel را نگهداری می‌کند. این فایل باید در مسیر اصلی پروژه قرار داشته باشد و از طریق وب قابل دسترسی نباشد.
نمونه تنظیمات پایگاه داده:
APP_NAME="Example App"
APP_ENV=production
APP_DEBUG=false
APP_URL=https://example.com
DB_CONNECTION=mysql
DB_HOST=localhost
DB_PORT=3306
DB_DATABASE=account_example
DB_USERNAME=account_example
DB_PASSWORD=YOUR_SECURE_PASSWORD
در این نمونه، example.com و مقادیر پایگاه داده فرضی هستند. آن‌ها را با اطلاعات واقعی خود جایگزین کنید.
در بسیاری از هاست‌های cPanel، مقدار DB_HOST برابر localhost است؛ اما این مقدار همیشگی نیست. اگر شرکت میزبانی آدرس جداگانه‌ای برای پایگاه داده ارائه کرده، همان آدرس را استفاده کنید.
همچنین:
- مقدار
APP_DEBUGباید در Production برابرfalseباشد. - مقدار
APP_URLباید با آدرس واقعی سایت هماهنگ باشد. - رمز پایگاه داده نباید در کد عمومی یا مخزن عمومی Git قرار بگیرد.
- اگر پروژه از قبل
APP_KEYمعتبر دارد، آن را بدون دلیل تغییر ندهید.
اگر پروژه جدید است و هنوز کلید برنامه ندارد، پس از نصب وابستگی‌ها می‌توانید دستور زیر را اجرا کنید:
php artisan key:generate
مرحله هفتم: نصب وابستگی‌های Composer روی هاست
اگر Composer روی هاست در دسترس است، می‌توانید از ترمینال cPanel یا SSH برای نصب وابستگی‌ها استفاده کنید.
ابتدا وارد مسیر اصلی پروژه شوید:
cd ~/laravel-app
سپس دستور زیر را اجرا کنید:
composer install --no-dev --optimize-autoloader
اگر دستور composer در دسترس نیست، باید روش مورد تأیید شرکت میزبانی را بررسی کنید. در برخی هاست‌ها امکان اجرای Composer از طریق ترمینال وجود ندارد یا محدودیت‌هایی برای آن اعمال شده است.
در چنین شرایطی می‌توان وابستگی‌ها را در محیطی سازگار آماده و پوشه vendor را همراه پروژه منتقل کرد؛ اما محیط ساخت باید با نسخه PHP و سیستم مقصد سازگار باشد.
پس از انتقال، مجوزها و کامل‌بودن وابستگی‌ها را بررسی کنید.
مرحله هشتم: اجرای Migrationهای Laravel
پس از تنظیم پایگاه داده و نصب وابستگی‌ها، باید جداول موردنیاز پروژه را ایجاد کنید.
اگر به ترمینال دسترسی دارید، در مسیر پروژه اجرا کنید:
php artisan migrate:status
برای اجرای Migrationهای جدید در محیط Production:
php artisan migrate --force
پیش از اجرای این دستور روی سایت اصلی، تغییرات Migrationها را بررسی کنید و از پایگاه داده نسخه پشتیبان تهیه کنید.
اگر SSH یا Terminal در دسترس نیست، از روش مورد تأیید شرکت میزبانی برای اجرای دستورات Laravel استفاده کنید. بهتر است برای اجرای مکرر فرمان‌های مدیریتی، دسترسی ترمینال یا یک فرایند Deploy استاندارد داشته باشید؛ اجرای فرمان‌های حساس از طریق اسکریپت‌های عمومی وب می‌تواند خطر امنیتی ایجاد کند.
مرحله نهم: تنظیم دسترسی پوشه‌های Laravel
Laravel برای ذخیره گزارش‌ها، فایل‌های کش و برخی داده‌های اجرایی به دسترسی نوشتن نیاز دارد.
دو مسیر مهم عبارت‌اند از:
storage/
bootstrap/cache/
اگر این پوشه‌ها قابل‌نوشتن نباشند، ممکن است خطاهای 500 یا خطاهای مربوط به ثبت گزارش مشاهده کنید.
در هاست اشتراکی، مالکیت فایل‌ها و مجوزهای لازم را بر اساس دستورالعمل شرکت میزبانی تنظیم کنید. مجوزهای موردنیاز به کاربری که PHP را اجرا می‌کند و تنظیمات PHP-FPM یا سایر Handlerهای PHP بستگی دارند.
از تنظیم مجوز 777 برای کل پروژه خودداری کنید. به‌جای آن، حداقل مجوز لازم را فقط برای مسیرهای موردنیاز فراهم کنید.
مرحله دهم: تنظیم کش و بهینه‌سازی Laravel
پس از تنظیم محیط Production، می‌توانید کش‌های Laravel را آماده کنید.
اگر به ترمینال دسترسی دارید، ابتدا در صورت نیاز کش‌های قبلی را پاک کنید:
php artisan optimize:clear
سپس دستورهای بهینه‌سازی را اجرا کنید:
php artisan config:cache
php artisan route:cache
php artisan view:cache
این دستورات برای آماده‌سازی کش تنظیمات، مسیرها و Viewها کاربرد دارند.
اگر پروژه از قابلیت‌هایی استفاده می‌کند که با Route Cache یا Config Cache سازگار نیستند، باید پیش از فعال‌سازی آن‌ها رفتار برنامه را بررسی کنید.
در صورت تغییر فایل .env، ممکن است لازم باشد کش تنظیمات را پاک کرده و دوباره بسازید.
مرحله یازدهم: بررسی اجرای سایت
پس از انجام مراحل نصب، سایت را با دامنه خود باز کنید.
موارد زیر را بررسی کنید:
- صفحه اصلی بدون خطا باز شود.
- اتصال به پایگاه داده برقرار باشد.
- مسیرهای اصلی پروژه کار کنند.
- فایل‌های CSS و JavaScript بارگذاری شوند.
- تصاویر و فایل‌های آپلودشده قابل دسترسی باشند.
- ورود، ثبت‌نام و سایر قابلیت‌های مهم کار کنند.
- گواهی HTTPS معتبر باشد.
- گزارش خطاهای Laravel قابل بررسی باشد.
اگر خطای 500 دریافت کردید، ابتدا گزارش‌های داخل storage/logs را بررسی کنید. همچنین تنظیمات فایل .env، دسترسی پوشه‌ها و نسخه PHP را دوباره بررسی کنید.
در هاست اشتراکی، مسیر و دسترسی گزارش‌های وب‌سرور ممکن است فقط در اختیار شرکت میزبانی باشد؛ در این صورت، از پشتیبانی هاست کمک بگیرید.
اجرای Queue و Task Scheduling در cPanel
برخی پروژه‌های Laravel از Queue برای ارسال ایمیل، پردازش فایل یا اجرای کارهای پس‌زمینه استفاده می‌کنند. بعضی دیگر برای اجرای وظایف دوره‌ای به Task Scheduling نیاز دارند.
در cPanel معمولاً می‌توان از بخش Cron Jobs برای اجرای وظایف زمان‌بندی‌شده استفاده کرد.
برای مثال، اگر مسیر PHP و مسیر پروژه مشخص باشند، می‌توان دستور Scheduler را به شکل زیر تعریف کرد:
cd /home/USERNAME/laravel-app && /usr/local/bin/php artisan schedule:run
مسیر PHP در این مثال فرضی است و باید با مسیر واقعی ارائه‌شده توسط شرکت میزبانی جایگزین شود. در بسیاری از سرورها مسیر PHP متفاوت است.
برای Queue Worker، به یاد داشته باشید که اجرای دائمی Worker معمولاً به فرایند مدیریت‌شده نیاز دارد. اگر هاست اجازه اجرای پردازش دائمی نمی‌دهد، باید از امکانات جایگزین مورد تأیید میزبان یا محیطی مانند VPS استفاده کنید.
خطاهای رایج هنگام نصب Laravel روی cPanel
خطای 500 پس از انتقال پروژه
این خطا می‌تواند ناشی از تنظیمات نادرست .env، نسخه ناسازگار PHP، مجوزهای فایل یا نصب ناقص وابستگی‌ها باشد.
ابتدا گزارش Laravel را بررسی کنید و از فعال‌کردن APP_DEBUG روی سایت عمومی خودداری کنید.
خطای اتصال به پایگاه داده
نام پایگاه داده، نام کاربر، رمز عبور و آدرس سرور پایگاه داده را بررسی کنید. فراموش نکنید که در cPanel ممکن است نام واقعی پایگاه داده و کاربر دارای پیشوند حساب هاست باشد.
نمایش صفحه Index یا خطای 403
این مشکل ممکن است به تنظیم نادرست Document Root یا مجوزهای فایل مربوط باشد. مطمئن شوید دامنه به پوشه public پروژه اشاره می‌کند و فایل index.php در آن مسیر وجود دارد.
خطای Vite یا نمایش‌ندادن فایل‌های CSS
اگر پروژه از Vite استفاده می‌کند، باید فایل‌های نهایی Build شده باشند و فایل manifest.json و دارایی‌های موردنیاز در مسیر درست قرار داشته باشند.
در دسترس نبودن Composer
اگر ترمینال یا Composer روی هاست فعال نیست، روش نصب وابستگی‌ها را با پشتیبانی شرکت میزبانی بررسی کنید. برای پروژه‌های پیچیده، هاستی که ابزارهای لازم را در اختیار قرار می‌دهد، فرایند استقرار را ساده‌تر می‌کند.
آیا cPanel برای همه پروژه‌های Laravel مناسب است؟
خیر. برای پروژه‌های ساده و متوسط که نیازمندی‌های آن‌ها با محدودیت‌های هاست سازگار است، cPanel می‌تواند گزینه مناسبی باشد.
اما اگر پروژه به Queueهای سنگین، پردازش دائمی، سرویس‌های متعدد، کنترل کامل تنظیمات سرور یا مقیاس‌پذیری پیشرفته نیاز دارد، استفاده از VPS یا زیرساخت کانتینری ممکن است انتخاب بهتری باشد.
مهم‌ترین معیار، انتخاب محیطی است که بتواند نیازمندی‌های فنی، امنیتی و عملیاتی پروژه را تأمین کند.
جمع‌بندی
برای نصب و Deploy لاراول روی cPanel باید نسخه PHP را با پروژه هماهنگ کنید، فایل‌ها و وابستگی‌ها را آماده سازید، پایگاه داده و فایل .env را تنظیم کنید و مطمئن شوید دامنه به پوشه public اشاره می‌کند.
پس از اجرای Migrationها و تنظیم مجوزهای لازم، سایت را از نظر عملکرد، امنیت و بارگذاری فایل‌ها آزمایش کنید.
به یاد داشته باشید که بالا آمدن صفحه اصلی به‌تنهایی به معنی آماده‌بودن پروژه برای Production نیست. تنظیم HTTPS، مدیریت اطلاعات محرمانه، تهیه نسخه پشتیبان و بررسی وظایف پس‌زمینه نیز از مراحل مهم استقرار محسوب می‌شوند.
سوالات متداول
آیا می‌توان Laravel را مستقیماً داخل public_html نصب کرد؟
بهتر است فایل‌های اصلی پروژه خارج از پوشه عمومی وب قرار بگیرند و فقط محتوای پوشه public در معرض دسترسی وب باشد. اگر محدودیت هاست اجازه این ساختار را نمی‌دهد، باید راهکار امن و سازگار با تنظیمات همان هاست انتخاب شود.
آیا برای نصب Laravel روی cPanel به SSH نیاز داریم؟
SSH الزامی نیست، اما دسترسی به ترمینال و Composer فرایند نصب و مدیریت پروژه را ساده‌تر می‌کند. بدون آن، باید از امکانات شرکت میزبانی یا روش آماده‌سازی وابستگی‌ها در محیط دیگری استفاده کنید.
آیا Laravel روی هاست اشتراکی اجرا می‌شود؟
بله، اگر نسخه PHP، افزونه‌ها، پایگاه داده و سایر نیازمندی‌های پروژه توسط هاست پشتیبانی شوند. پروژه‌هایی با نیازهای عملیاتی پیچیده ممکن است به VPS نیاز داشته باشند.
آیا می‌توان از Cron Job برای اجرای Scheduler لاراول استفاده کرد؟
بله. در صورت پشتیبانی هاست، می‌توان دستور php artisan schedule:run را طبق بازه زمانی مناسب در Cron Jobs تعریف کرد. مسیر PHP و پروژه باید با محیط واقعی هماهنگ باشند.
بعد از تغییر فایل .env چه کاری باید انجام داد؟
اگر تنظیمات Laravel کش شده باشند، ممکن است لازم باشد کش تنظیمات را پاک کنید و در صورت نیاز دوباره بسازید. همچنین مطمئن شوید مقادیر جدید با تنظیمات واقعی هاست هماهنگ هستند.
