روی لپتاپ همه چیز درست کار میکند. php artisan serve را میزنید، صفحه بالا میآید، فرمها ثبت میشوند. بعد پروژه را روی سرور میبرید و اولین چیزی که میبینید یک صفحهٔ سفید با خطای 500 است. یا بدتر، صفحهٔ خطای رنگی لاراول که رمز دیتابیس را جلوی چشم همهٔ بازدیدکنندهها گذاشته است.
دیپلوی لاراول سخت نیست، ولی چند قدم دارد که اگر یکی جا بیفتد، سایت یا بالا نمیآید یا ناامن بالا میآید. این راهنما همان قدمها را به ترتیب میآورد: چه چیزی باید روی سرور برسد، فایل .env عملیاتی چه شکلی است، روی VPS و روی هاست ابری چه دستورهایی اجرا میشود، صف و زمانبند را چطور زنده نگه دارید و بعد از دیپلوی چه چیزهایی را چک کنید. آخر مقاله هم جدول خطاهای رایج و راه رفعشان آمده است.
دیپلوی لاراول یعنی چه؟
دیپلوی (Deploy) یعنی کدی که روی سیستم خودتان نوشتهاید، روی سروری اجرا شود که کاربر واقعی به آن وصل میشود. در لاراول این کار فقط کپی فایل نیست. باید وابستگیهای Composer نصب شوند، فایلهای فرانت با Vite ساخته شوند، جدولهای دیتابیس با migration ساخته یا بهروز شوند، کش تنظیمات و مسیرها ساخته شود و پروسههای پسزمینه مثل صف دوباره راه بیفتند.
یک قاعدهٔ ساده کمک میکند: هر چیزی که در گیت هست، روی سرور هم باید برسد؛ هر چیزی که در .gitignore است، روی سرور ساخته یا جداگانه تنظیم میشود. پوشهٔ vendor با composer install ساخته میشود، node_modules اصلاً روی سرور لازم نیست، و .env را هیچوقت در مخزن کد نمیگذارید.
| بخش پروژه | در گیت؟ | روی سرور چطور میرسد |
|---|---|---|
کد برنامه (app، routes، resources، config) |
بله | با git، CLI یا FTP |
vendor |
خیر | composer install روی سرور |
public/build (خروجی Vite) |
معمولاً خیر | npm run build روی سرور یا در CI و ارسال خروجی |
.env |
هرگز | دستی روی سرور یا متغیرهای محیطی پنل |
storage/app و فایلهای آپلودی |
خیر | روی سرور میمانند؛ باید از بازنویسی در دیپلوی بعدی محافظت شوند |
پیشنیازهای سرور برای دیپلوی لاراول
طبق مستند رسمی دیپلوی لاراول، نسخهٔ فعلی فریمورک (Laravel 13) دستکم PHP 8.3 میخواهد و این اکستنشنها باید روی سرور فعال باشند: Ctype، cURL، DOM، Fileinfo، Filter، Hash، Mbstring، OpenSSL، PCRE، PDO، Session، Tokenizer و XML. اگر پروژهتان روی نسخهٔ قدیمیتر است، بازهٔ PHP هر نسخه را در جدول پشتیبانی نسخهها ببینید؛ مثلاً Laravel 11 با PHP 8.2 تا 8.4 کار میکند.
قبل از هر کاری، بخش require فایل composer.json را باز کنید و نسخهٔ PHP روی سرور را با آن تطبیق بدهید. بخش بزرگی از خطاهای «روی سیستم من کار میکرد» از همین اختلاف نسخه میآید.
جز PHP به اینها هم نیاز دارید:
- وبسرور: Nginx یا Apache که همهٔ درخواستها را به
public/index.phpبفرستد. ریشهٔ سایت باید پوشهٔpublicباشد، نه ریشهٔ پروژه؛ وگرنه فایلهایی مثل.envاز اینترنت قابل دسترسی میشوند. - دیتابیس: MySQL، MariaDB یا PostgreSQL. اگر هنوز بین اینها مردد هستید، مقایسهٔ MySQL و PostgreSQL را بخوانید.
- Composer روی سرور، و اگر فرانت را روی سرور میسازید، Node.js.
- دسترسی نوشتن برای پروسهٔ وبسرور روی پوشههای
storageوbootstrap/cache.
سه مسیر رایج برای دیپلوی لاراول
برای دیپلوی لاراول سه گزینهٔ معمول دارید و هر کدام مقدار متفاوتی کار روی دوش شما میگذارد:
| معیار | هاست اشتراکی (cPanel/DirectAdmin) | سرور مجازی (VPS) | هاست ابری (PaaS) |
|---|---|---|---|
| نصب PHP و وبسرور | از قبل نصب است ولی محدود | با شما | آماده؛ نسخهٔ PHP از پنل انتخاب میشود |
| دسترسی ترمینال و Artisan | گاهی هست، گاهی نه | کامل | از طریق کنسول سرویس |
| صف و Supervisor | معمولاً ممکن نیست | خودتان نصب و تنظیم میکنید | با یک فایل تنظیم در ریشهٔ پروژه |
| Cron برای زمانبند | از پنل هاست | با crontab | با فایل تنظیم در ریشهٔ پروژه |
| SSL، فایروال و بهروزرسانی سیستمعامل | با میزبان | با شما | با میزبان |
| مناسب برای | پروژهٔ خیلی ساده بدون صف | تیمی که کنترل کامل سرور را میخواهد | تیمی که میخواهد روی کد تمرکز کند |
روی هاست اشتراکی معمولاً مجبورید محتوای public را جابهجا کنید یا با rewrite دور بزنید، که هم خطاساز است و هم خلاف توصیهٔ خود لاراول. اگر بین دو گزینهٔ بعدی تردید دارید، مقایسهٔ PaaS و VPS و PaaS چیست تفاوت هزینهٔ نگهداری را باز کردهاند.
آمادهسازی پروژه قبل از دیپلوی لاراول
این کارها را روی سیستم خودتان انجام بدهید، قبل از اینکه حتی سراغ سرور بروید:
- فایل
.envعملیاتی را جدا بنویسید.APP_ENVرویproductionوAPP_DEBUGرویfalse. مستند لاراول صریح میگوید روشن ماندن debug در محیط عملیاتی مقادیر حساس تنظیمات را به کاربر نشان میدهد. APP_KEYرا بسازید و نگه دارید. این کلید برای رمزنگاری سشن و کوکیها استفاده میشود. اگر بعداً عوضش کنید، کاربران از حساب خارج میشوند و دادههای رمزشده با کلید قبلی دیگر خوانده نمیشوند.- در کد مستقیماً
env()صدا نزنید. بعد ازconfig:cache، فایل.envدیگر خوانده نمیشود و هرenv()بیرون از پوشهٔconfigمقدارnullبرمیگرداند. مقدار را در یک فایل config بگذارید و باconfig()بخوانید. - migrationها را تست کنید. یک بار روی دیتابیس خالی
php artisan migrate:freshبزنید تا مطمئن شوید از صفر کامل اجرا میشوند. composer.lockرا commit کنید. بدون آن، سرور ممکن است نسخهٔ دیگری از پکیجها نصب کند.
یک نمونهٔ حداقلی از .env عملیاتی:
APP_NAME=MyShop
APP_ENV=production
APP_KEY=base64:GENERATED_BY_KEY_GENERATE
APP_DEBUG=false
APP_URL=https://example.com
LOG_CHANNEL=stack
LOG_LEVEL=warning
DB_CONNECTION=mysql
DB_HOST=db-host
DB_PORT=3306
DB_DATABASE=myshop
DB_USERNAME=myshop_user
DB_PASSWORD=change-me
CACHE_STORE=redis
QUEUE_CONNECTION=redis
SESSION_DRIVER=redis
REDIS_HOST=redis-host
اگر Redis ندارید، CACHE_STORE و QUEUE_CONNECTION را روی database بگذارید؛ برای شروع کافی است.
دیپلوی لاراول روی VPS قدمبهقدم
فرض میکنیم روی سرور مجازی اوبونتو، PHP و Nginx و Composer نصب شدهاند و دیتابیس آماده است. اولین دیپلوی این شکلی است:
cd /var/www
git clone git@github.com:you/myshop.git
cd myshop
composer install --no-dev --optimize-autoloader
cp .env.example .env # then edit production values
php artisan key:generate
npm ci && npm run build
php artisan migrate --force
php artisan storage:link
php artisan optimize
sudo chown -R www-data:www-data storage bootstrap/cache
چند نکته دربارهٔ همین دستورها:
--no-devپکیجهای توسعه مثل ابزار تست را نصب نمیکند و--optimize-autoloaderنقشهٔ کلاسها را از قبل میسازد.migrate --forceلازم است چون لاراول در محیط production بدون این سوئیچ قبل از اجرای migration تأیید میخواهد.php artisan optimizeکش تنظیمات، رویدادها، مسیرها و viewها را یکجا میسازد. اگر تنظیمی را عوض کردید و اثری نداشت، اولphp artisan optimize:clearرا بزنید.key:generateفقط بار اول. در دیپلویهای بعدی به آن دست نزنید.
در Nginx، root باید به /var/www/myshop/public اشاره کند. نمونهٔ کامل تنظیمات Nginx در همان مستند رسمی آمده است. بعد از آن SSL را با Certbot یا هر روش دیگری فعال کنید و APP_URL را با https بنویسید.
دیپلویهای بعدی کوتاهترند:
cd /var/www/myshop
php artisan down
git pull origin main
composer install --no-dev --optimize-autoloader
npm ci && npm run build
php artisan migrate --force
php artisan optimize
php artisan queue:restart
php artisan up
همین چند خط را در یک اسکریپت deploy.sh بگذارید تا هر بار ترتیب یکسان بماند. قدم بعدی این است که با هر push به شاخهٔ اصلی خودکار اجرا شود؛ ایدهٔ کلیاش را در استقرار خودکار چیست نوشتهایم.

دیپلوی لاراول روی هاست ابری چابکان
روی هاست ابری، نصب PHP، وبسرور، SSL و بهروزرسانی سیستمعامل با میزبان است و شما فقط کد و تنظیمات را میدهید. در هاست ابری لاراول چابکان مسیر اینطور است:
- ساخت سرویس: از داشبورد، ساخت سرویس جدید ← هاست ابری ← Laravel. نسخهٔ PHP را بعداً از تنظیمات سرویس هم میتوانید عوض کنید؛ فهرست نسخههای قابل انتخاب در مستند استقرار Laravel آمده است.
- ارسال کد: روش پیشنهادی CLI است. بعد از نصب CLI، با
chabok loginوارد میشوید و در پوشهٔ پروژهchabok deployرا میزنید. git از داخل کنسول سرویس، FTP و فایلمنیجر هم پشتیبانی میشوند. اگر حجم پروژه از 100 مگابایت بیشتر است، مستندات FTP را پیشنهاد میکند. جزئیات در راهنمای استقرار با CLI. - متغیرهای محیطی: مقادیر
.envرا در تنظیمات سرویس، بخش متغیرهای محیطی وارد کنید. ذخیرهٔ این بخش سرویس را دوباره مستقر میکند. - دیتابیس: یک دیتابیس ابری MySQL یا دیگر موتورهای دیتابیس ابری بسازید و
DB_HOST،DB_PORT،DB_DATABASE،DB_USERNAMEوDB_PASSWORDرا از داشبورد همان دیتابیس در متغیرهای محیطی بگذارید. - Migration: از منوی سرویس، کنسول را باز کنید و
php artisan migrate --forceرا بزنید.
سه نکتهٔ مخصوص این محیط که اگر ندانید، وقت میگیرند:
- مسیرهای دائمی: با هر دیپلوی از طریق CLI، فایلهای قبلی سرویس پاک و نسخهٔ جدید جایگزین میشود. پوشهٔ
storage(فایلهای آپلودی، لاگها) را بعد از اولین دیپلوی در بخش مسیرهای دائمی ثبت کنید تا در دیپلوی بعدی حذف نشود. - پروکسی معکوس: درخواستها از پروکسی معکوس چابکان به سرویس میرسند. اگر لاراول پروکسی را trust نکند، لینکها با http ساخته میشوند و فرمها خطای Mixed Content میدهند. در Laravel 11 به بعد در
bootstrap/app.phpاز$middleware->trustProxies(at: '*')استفاده کنید؛ در نسخههای قدیمیتر فایلTrustProxies.phpرا طبق نکات تکمیلی Laravel تغییر دهید. - تنظیمات php.ini: برای عوضکردن مقادیری مثل
upload_max_filesizeیاmemory_limit، فایلی به نامchabok-php.iniدر ریشهٔ پروژه بسازید و سرویس را یک بار ریاستارت کنید.
اگر Composer موقع نصب پکیجها کند بود یا به packagist نرسید، همان صفحهٔ نکات تکمیلی آدرس میرور Composer چابکان را دارد که در بخش repositories فایل composer.json مینشیند.
صف و زمانبند: بخشهایی که بعد از دیپلوی فراموش میشوند
سایت بالا آمده، ولی ایمیلهای تأیید ارسال نمیشوند و گزارش شبانه هم ساخته نمیشود. دلیلش معمولاً این است که پروسههای پسزمینه را کسی روشن نکرده است. لاراول در محیط عملیاتی سه بخش اجرایی دارد:
| بخش | دستور | چه کسی اجرایش میکند | بعد از هر دیپلوی |
|---|---|---|---|
| وب | public/index.php |
PHP-FPM یا Apache | کشها را با optimize بازسازی کنید |
| صف (Queue) | php artisan queue:work |
Supervisor | php artisan queue:restart |
| زمانبند (Scheduler) | php artisan schedule:run |
Cron، هر دقیقه | کاری لازم نیست |
صف: ورکر صف یک پروسهٔ طولانی است و کد را یک بار در حافظه بار میکند. اگر بعد از دیپلوی آن را ریاستارت نکنید، با کد قدیمی به کارش ادامه میدهد. queue:restart به ورکرها میگوید بعد از تمامکردن کار فعلی خارج شوند و Supervisor دوباره بالا میآوردشان. روی VPS یک فایل تنظیم Supervisor میسازید؛ نمونهٔ کاملش در مستند صف لاراول هست. در هاست ابری چابکان کافی است فایلی به نام supervisor.conf در ریشهٔ پروژه بگذارید و سرویس را ریاستارت کنید:
[program:app-worker]
process_name=%(program_name)s_%(process_num)02d
command=php /var/www/html/artisan queue:work --tries=3
directory=/var/www/html
autostart=true
autorestart=true
numprocs=1
redirect_stderr=true
stdout_logfile=/app-worker.log
زمانبند: طبق مستند Task Scheduling، کل زمانبندی لاراول با یک خط cron اجرا میشود که هر دقیقه schedule:run را صدا میزند و خود لاراول تصمیم میگیرد کدام کار وقتش رسیده است. روی VPS این خط را در crontab -e میگذارید. در چابکان فایلی به نام cron-jobs در ریشهٔ پروژه میسازید؛ مسیر پروژه در سرویس Laravel برابر /var/www/html است:
* * * * * cd /var/www/html && php artisan schedule:run >> /dev/null 2>&1
این فایل موقع راهاندازی سرویس خوانده میشود، پس بعد از هر تغییر سرویس را ریاستارت کنید. آخر فایل هم یک خط خالی بگذارید. راهنماهای کامل: Supervisor در چابکان و Cron Job در چابکان.

فایلهای آپلودی کجا بمانند؟
لاراول فایلهای عمومی را در storage/app/public نگه میدارد و با php artisan storage:link یک لینک نمادین از public/storage به آن میسازد. دو اشتباه رایج اینجا پیش میآید: لینک را بعد از دیپلوی نمیسازند و تصاویر 404 میدهند، یا پوشهٔ storage در هر دیپلوی بازنویسی میشود و آپلودهای کاربران پاک میشوند.
اگر فقط یک سرور دارید، محافظت از storage (روی VPS با نگهداشتنش بیرون از مسیری که git بازنویسی میکند، در چابکان با مسیر دائمی) کافی است. اگر میخواهید بعداً چند نمونه از برنامه را کنار هم اجرا کنید یا حجم فایلها زیاد است، دیسک لاراول را روی فضای سازگار با S3 ببرید. لاراول درایور S3 دارد و با پکیج league/flysystem-aws-s3-v3 به هر فضای سازگار وصل میشود. فضای ذخیرهسازی ابری چابکان با پروتکل S3 سازگار است و مراحل اتصالش در مستند اتصال Laravel به S3 آمده است. مفهوم کلی را هم در فضای ذخیرهسازی S3 چیست توضیح دادهایم.
چکلیست بعد از دیپلوی لاراول
قبل از اینکه لینک را برای مشتری یا تیم بفرستید، این موارد را یکییکی بررسی کنید:
- آدرس
/upرا باز کنید. لاراول از نسخهٔ 11 این مسیر سلامت را دارد و اگر برنامه بدون خطا بوت شود، کد 200 برمیگرداند. همین آدرس را به سرویس مانیتورینگ آپتایم بدهید. - یک صفحهٔ ناموجود را باز کنید. باید صفحهٔ 404 ساده ببینید، نه صفحهٔ دیباگ با مسیر فایلها.
- آدرس
https://example.com/.envرا امتحان کنید. باید 404 یا 403 بگیرید. - ثبتنام یا یک فرم را تست کنید تا سشن، CSRF و ارسال ایمیل از طریق صف معلوم شوند.
- یک فایل آپلود کنید و مطمئن شوید آدرسش باز میشود.
storage/logs/laravel.logیا بخش لاگهای سرویس را نگاه کنید. خطای تکرارشوندهای نباید باشد.- بکاپ دیتابیس را بررسی کنید. اولین migration روی دادهٔ واقعی بهترین زمان برای داشتن یک بکاپ سالم است.
خطاهای رایج بعد از دیپلوی لاراول
| خطا یا نشانه | علت محتمل | راه رفع |
|---|---|---|
| صفحهٔ سفید یا خطای 500 بدون توضیح | دسترسی نوشتن روی storage یا bootstrap/cache نیست، یا نسخهٔ PHP با پروژه نمیخواند |
لاگ لاراول و لاگ وبسرور را ببینید؛ مالکیت پوشهها و نسخهٔ PHP را درست کنید |
No application encryption key has been specified |
APP_KEY خالی است |
بار اول php artisan key:generate و بعد کش تنظیمات را دوباره بسازید |
تنظیم جدید در .env اثر ندارد |
کش تنظیمات قدیمی است | php artisan optimize:clear و دوباره optimize |
مقدار env() در کد null است |
env() بیرون از پوشهٔ config صدا زده شده و config کش شده است |
مقدار را به یک فایل config ببرید و با config() بخوانید |
| خطای 419 Page Expired در فرمها | سشن ذخیره نمیشود یا دامنهٔ کوکی با APP_URL نمیخواند |
SESSION_DRIVER، SESSION_DOMAIN و https بودن APP_URL را بررسی کنید |
| لینکها و assetها با http ساخته میشوند | پروکسی معکوس trust نشده است | trustProxies را تنظیم کنید |
Vite manifest not found |
فرانت روی سرور build نشده است | npm run build را اجرا کنید یا پوشهٔ public/build را بفرستید |
| تصاویر آپلودی 404 میدهند | لینک public/storage ساخته نشده یا پوشه پاک شده |
php artisan storage:link و محافظت از مسیر storage |
| ایمیلها و jobها اجرا نمیشوند | ورکر صف روشن نیست یا با کد قدیمی کار میکند | Supervisor را بررسی و queue:restart را به اسکریپت دیپلوی اضافه کنید |
Call to undefined function ... shell_exec() |
تابعهای exec و shell_exec به دلایل امنیتی بستهاند |
در چابکان طبق مستند مشکلات احتمالی عمل کنید |
کدام مسیر برای دیپلوی لاراول مناسبتر است؟
اگر میخواهید Nginx را خودتان تنظیم کنید، روی سرور Redis و Meilisearch و ابزارهای دیگر هم نصب کنید و از کار با لینوکس لذت میبرید، سرور ابری انعطاف کامل میدهد. فقط یادتان باشد امنیت، بهروزرسانی، بکاپ و مانیتورینگ هم از همان روز اول کار شماست.
اگر ترجیح میدهید وقت تیم صرف کد شود، هاست ابری لاراول چابکان PHP و وبسرور آماده، کنسول برای Artisan، Supervisor و Cron با یک فایل، SSL و بکاپ خودکار را یکجا میدهد. منابع سرویس را هم هر وقت لازم شد از پنل بالا میبرید. پلنها و امکانات هر کدام را در جدول تعرفهٔ صفحهٔ هاست لاراول مقایسه کنید. اگر سایت فعلیتان جای دیگری است، راهنمای انتقال سایت به هاست جدید مراحل جابهجایی را توضیح داده است.
سؤالات متداول
دیپلوی لاراول روی هاست اشتراکی cPanel ممکن است؟
ممکن است، ولی با محدودیت. باید ریشهٔ دامنه را به پوشهٔ public ببرید و اگر پنل اجازه نمیدهد، به ترفندهایی مثل جابهجایی index.php رو میآورید که مستند لاراول صریحاً از آن منع میکند. صف دائمی هم معمولاً روی هاست اشتراکی اجرا نمیشود. برای پروژهٔ جدی، VPS یا هاست ابری انتخاب امنتری است.
آیا پوشهٔ vendor را روی سرور آپلود کنم؟
بهتر است نه. composer.lock را بفرستید و روی سرور composer install --no-dev بزنید تا همان نسخههای دقیق نصب شوند. آپلود vendor از ویندوز روی سرور لینوکس گاهی به مشکل مسیر و دسترسی میخورد. در هاست ابری چابکان نصب پکیجها بعد از دیپلوی خودکار انجام میشود.
بعد از هر دیپلوی لاراول کدام دستورها را باید اجرا کنم؟
حداقل composer install --no-dev --optimize-autoloader، php artisan migrate --force، php artisan optimize و اگر صف دارید php artisan queue:restart. اگر فرانت با Vite دارید، npm run build هم لازم است.
APP_DEBUG را کی روشن کنم؟
در محیط عملیاتی هیچوقت. برای پیدا کردن خطا، لاگ storage/logs یا لاگهای سرویس را بخوانید. اگر لازم است خطا را موقتاً ببینید، روی یک نسخهٔ staging جدا این کار را بکنید.
دیتابیس را کنار برنامه روی همان سرور نصب کنم یا جدا؟
برای شروع روی یک VPS، نصب کنار برنامه سادهتر است. وقتی ترافیک بالا رفت یا خواستید برنامه را روی چند سرور اجرا کنید، دیتابیس جدا و مدیریتشده بکاپ و بهروزرسانی را از دوش شما برمیدارد و منابع برنامه با کوئریهای سنگین درگیر نمیشود.
Laravel Octane را هم میتوانم روی هاست ابری اجرا کنم؟
در سرویس Laravel چابکان بله. با مقداردهی متغیر محیطی START_COMMAND به دستور php artisan octane:start --server=swoole --host=0.0.0.0 --port=80 سرویس با Octane بالا میآید. قبلش مطمئن شوید کدتان با اجرای ماندگار در حافظه سازگار است؛ مثلاً state سراسری بین درخواستها نشت نکند.