مقاله

نصب کامل Laravel 12 روی ویندوز ۱۱ با XAMPP، Composer و PHP 8.3 — از دانلود تا اجرای اولین پروژه، همراه با رفع خطاهای رایج و تنظیمات پیشنهادی برای توسعه محلی.

آموزش نصب Laravel 12 روی ویندوز با XAMPP — راهنمای گام‌به‌گام ۱۴۰۵
لاراول

آموزش نصب Laravel 12 روی ویندوز با XAMPP — راهنمای گام‌به‌گام ۱۴۰۵

2026/02/25 3 دقیقه مطالعه 7 بازدید Emran Jamshidi
Laravel PHP

اولین قدم برای یادگیری Laravel روی ویندوز، یک محیط توسعه پایدار است. XAMPP هنوز برای بسیاری از توسعه‌دهندگان ایرانی انتخاب اول است — چون نصب ساده دارد، Apache و MySQL را یک‌جا می‌آورد و با مسیر C:\xampp\htdocs برای کسانی که سال‌ها با PHP کار کرده‌اند آشناست. در این راهنما Laravel 12 را با PHP 8.3، Composer و XAMPP راه‌اندازی می‌کنیم؛ نه به‌صورت تئوری، بلکه همان مسیری که در پروژه‌های واقعی روی لپ‌تاپ ویندوزی طی می‌کنم.

چرا نصب درست Laravel از همان ابتدا مهم است؟

بیشتر خطاهای «لاراول روی سیستم من کار نمی‌کند» ریشه در نسخه PHP، اکستنشن‌های ناقص یا مسیر اشتباه Composer دارند. اگر این پایه درست نباشد، هر آموزش بعدی — از Eloquent تا Queue — روی شن و بنا ساخته می‌شود. Google هم برای جستجوهای آموزشی مثل «نصب لاراول ۱۲» محتوایی را ترجیح می‌دهد که تجربه واقعی، عیب‌یابی و نسخه‌های به‌روز را پوشش دهد؛ نه فقط دستور composer create-project بدون توضیح.

پیش‌نیازهای سخت‌افزاری و نرم‌افزاری

ویندوز ۱۰ یا ۱۱ (۶۴ بیت)، حداقل ۸ گیگ RAM (۱۶ گیگ برای Docker یا چند پروژه همزمان بهتر است)، فضای آزاد ۵ گیگ برای XAMPP، Composer و vendorها. به اتصال اینترنت پایدار برای Composer نیاز دارید — در ایران گاهی تنظیم mirror یا VPN برای دانلود پکیج‌ها لازم می‌شود.

مرحله ۱ — نصب و به‌روزرسانی XAMPP

از سایت رسمی Apache Friends آخرین نسخه XAMPP با PHP 8.2 یا 8.3 را دانلود کنید. Laravel 12 به PHP 8.2+ نیاز دارد؛ اگر XAMPP شما PHP 8.1 دارد، یا XAMPP را آپدیت کنید یا PHP را جداگانه نصب و PATH را تنظیم کنید.

پس از نصب، XAMPP Control Panel را باز کنید و Apache و MySQL را Start کنید. اگر پورت ۸۰ اشغال است (مثلاً توسط IIS یا Skype)، در httpd.conf پورت را به ۸۰۸۰ تغییر دهید یا سرویس متعارض را متوقف کنید.

فعال‌سازی اکستنشن‌های PHP مورد نیاز Laravel

فایل C:\xampp\php\php.ini را باز کنید و خطوط زیر را از حالت کامنت خارج کنید (سمیکالن ابتدای خط را حذف کنید):

extension=curl
extension=fileinfo
extension=mbstring
extension=openssl
extension=pdo_mysql
extension=tokenizer
extension=xml
extension=zip
extension=intl

مقدار memory_limit را حداقل 256M و ترجیحاً 512M بگذارید. max_execution_time برای Composer بهتر است ۱۲۰ یا بیشتر باشد. Apache را از XAMPP Restart کنید.

در CMD یا PowerShell بررسی کنید:

C:\xampp\php\php.exe -v
C:\xampp\php\php.exe -m

خروجی باید PHP 8.2.x یا 8.3.x و لیست اکستنشن‌های فعال را نشان دهد.

مرحله ۲ — نصب Composer

Laravel بدون Composer نصب نمی‌شود. از getcomposer.org Windows Installer را بگیرید. هنگام نصب، مسیر PHP را به C:\xampp\php\php.exe اشاره دهید.

ترمینال جدید باز کنید:

composer -V
php -v

اگر php شناخته نشد، مسیر XAMPP را به متغیر محیطی PATH اضافه کنید: C:\xampp\php

تنظیم Composer برای سرعت بیشتر در ایران

گاهی mirror داخلی یا کش محلی کمک می‌کند. حداقل این را اجرا کنید:

composer config -g process-timeout 2000
composer config -g preferred-install dist

مرحله ۳ — ساخت پروژه Laravel 12

به پوشه htdocs بروید:

cd C:\xampp\htdocs
composer create-project laravel/laravel my-blog "12.*"

اگر نسخه ۱۲ هنوز در Packagist با تگ 12.* در دسترس بود، آخرین stable نصب می‌شود. نام پوشه را به دلخواه عوض کنید — مثلاً portfolio یا shop.

پس از اتمام، وارد پوشه پروژه شوید:

cd my-blog
copy .env.example .env
php artisan key:generate

فایل .env تنظیمات محیط را نگه می‌دارد. برای شروع محلی:

APP_NAME="My Blog"
APP_ENV=local
APP_DEBUG=true
APP_URL=http://127.0.0.1:8000

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=my_blog
DB_USERNAME=root
DB_PASSWORD=

در phpMyAdmin (http://localhost/phpmyadmin) دیتابیس my_blog با collation utf8mb4_unicode_ci بسازید. سپس:

php artisan migrate

مرحله ۴ — اجرای پروژه

ساده‌ترین روش برای توسعه:

php artisan serve

مرورگر: http://127.0.0.1:8000 — صفحه خوش‌آمد Laravel باید نمایش داده شود.

اجرا از طریق Apache (اختیاری)

برای URL شبیه production می‌توانید Virtual Host تعریف کنید. در C:\xampp\apache\conf\extra\httpd-vhosts.conf:

<VirtualHost *:80>
    DocumentRoot "C:/xampp/htdocs/my-blog/public"
    ServerName my-blog.test
    <Directory "C:/xampp/htdocs/my-blog/public">
        AllowOverride All
        Require all granted
    </Directory>
</VirtualHost>

فایل hosts ویندوز (C:\Windows\System32\drivers\etc\hosts):

127.0.0.1 my-blog.test

Document Root حتماً باید پوشه public باشد — نه ریشه پروژه. این یکی از رایج‌ترین اشتباهات امنیتی است.

خطاهای رایج و راه‌حل

خطای ext-* یا PHP version

پیام «your requirements could not be resolved» معمولاً یعنی PHP قدیمی یا اکستنشن غیرفعال. php -m را با نیازمندی‌های رسمی Laravel مقایسه کنید.

خطای SSL یا timeout در Composer

موقتاً composer config -g secure-http false (با احتیاط) یا استفاده از VPN. timeout را بالا ببرید.

خطای permission یا symlink

پوشه‌های storage و bootstrap/cache باید قابل نوشتن باشند. روی ویندوز معمولاً مشکل کمتری دارید؛ روی WSL متفاوت است.

صفحه ۵۰۰ بعد از migrate

لاگ را ببینید: storage/logs/laravel.log. اغلب مشکل از اتصال دیتابیس یا APP_KEY خالی است.

ساختار پوشه‌های Laravel 12 — نگاه سریع

پوشه app/ منطق اپلیکیشن (Models، Http/Controllers، Providers). routes/web.php و api.php مسیرها. resources/views Blade. database/migrations اسکیمای دیتابیس. config/ تنظیمات. در Laravel 12 ساختار کلی شبیه ۱۱ است؛ تغییرات نسخه را در Release Notes بخوانید.

بهترین شیوه‌ها برای توسعه محلی روی ویندوز

از Git از روز اول استفاده کنید. .env را commit نکنید. برای ادیتور، VS Code یا PhpStorm با افزونه‌های PHP Intelephense و Laravel Idea (یا رایگان: Laravel Extension Pack) کافی است. Laravel Pint برای فرمت کد: ./vendor/bin/pint

اگر چند پروژه دارید، به‌جای اشتراک یک XAMPP قدیمی، برای هر پروژه php artisan serve --port=8001 پورت جدا بگیرید یا از Laravel Herd (فقط ویندوز/macOS) برای مدیریت خودکار vhost استفاده کنید — در مقالات بعدی مقایسه می‌کنیم.

نکات امنیتی

روی محیط local، APP_DEBUG=true قابل قبول است؛ هرگز روی سرور production این‌طور نگذارید. کاربر root MySQL بدون رمز فقط برای localhost بماند. فایل .env را در وب‌سرور قابل دسترس نکنید — Document Root را روی public قفل کنید.

نکات عملکرد

برای local، Opcache را در php.ini فعال کنید. composer install --no-dev فقط برای deploy است، نه توسعه روزانه. از php artisan config:cache روی local معمولاً خودداری کنید تا تغییر .env فوری اعمال شود.

سؤالات متداول

در بخش FAQ اسکیمای پایین صفحه، پاسخ‌های کوتاه برای Featured Snippet آماده شده‌اند.

مقایسه روش‌های توسعه Laravel روی ویندوز

علاوه بر XAMPP، چند گزینه رایج دارید. Laravel Herd (رایگان برای استفاده شخصی) PHP چندنسخه و vhost خودکار می‌دهد — برای کسی که فقط Laravel/PHP می‌زند راحت‌تر از XAMPP است. Docker با Laravel Sail محیط یکسان با production می‌سازد اما روی ویندوز بدون WSL2 گاهی کند است. WSL2 + Ubuntu نزدیک‌ترین تجربه به سرور لینوکس است؛ من برای پروژه‌هایی که deploy روی Ubuntu دارند، تست نهایی را اغلب در WSL انجام می‌دهم.

XAMPP همچنان برای کسانی که تازه PHP را با phpMyAdmin و Apache یاد می‌گیرند بهترین نقطه شروع است. بعد از ۲–۳ ماه می‌توانید به Herd مهاجرت کنید بدون تغییر کد پروژه.

تنظیم دیتابیس پیشرفته برای توسعه

برای charset یکسان با production، در MySQL این را اجرا کنید:

CREATE DATABASE my_blog
  CHARACTER SET utf8mb4
  COLLATE utf8mb4_unicode_ci;

در Laravel migrationها معمولاً $table->timestamps() و $table->id() کافی است. اگر با خطای «Specified key was too long» مواجه شدید، در AppServiceProvider مقدار Schema::defaultStringLength(191) را برای MySQL قدیمی‌تر تنظیم کنید — در MariaDB 10.3+ و MySQL 8 اغلب لازم نیست.

نصب Node.js و Vite برای فرانت Laravel

Laravel 12 به‌طور پیش‌فرض از Vite برای assetها استفاده می‌کند. Node.js LTS را از nodejs.org نصب کنید، سپس در پوشه پروژه:

npm install
npm run dev

در یک ترمینال جدا php artisan serve را نگه دارید. اگر فعلاً فقط backend یاد می‌گیرید، می‌توانید از viewهای Blade ساده بدون build استفاده کنید؛ اما برای layout پیش‌فرض Laravel، Vite لازم می‌شود.

سناریوی واقعی: اولین CRUD بعد از نصب

پس از migrate موفق، این مسیر یادگیری را پیشنهاد می‌کنم:

php artisan make:model Article -mcr
# migration را در articles_table پر کنید
php artisan migrate
php artisan route:list

اگر route resource ساختید، با http://127.0.0.1:8000/articles (بسته به تعریف route) لیست را ببینید. این نقطهٔ اتصال نصب به اصول توسعه واقعی است — Controller را نازک نگه دارید.

چک‌لیست نهایی قبل از commit اول Git

  • PHP 8.2+ و اکستنشن‌ها OK
  • .env در gitignore و .env.example به‌روز
  • APP_KEY تولید شده
  • migrate بدون خطا
  • artisan serve صفحه Laravel را نشان می‌دهد
  • پوشه storage قابل نوشتن است

جمع‌بندی

نصب Laravel 12 روی ویندوز با XAMPP سه ستون دارد: PHP درست با اکستنشن‌ها، Composer پایدار، و پروژه‌ای که Document Root آن public است. بعد از artisan serve و یک migrate موفق، آماده‌اید سراغ routing و اولین CRUD بروید. اگر در مسیر شغلی تازه‌کار هستید، مقاله رودمپ برنامه‌نویسی وب ۱۴۰۵ را بخوانید؛ و برای معماری تمیز از همان هفته اول، ۱۰ اصل طلایی Laravel در پروژه‌های واقعی مرجع خوبی است.

نیاز به راه‌اندازی پروژه Laravel برای کسب‌وکار دارید؟ از صفحه تماس درخواست مشاوره بدهید — از نصب محلی تا deploy روی سرور لینوکس همراهتان هستم.

مقالات مرتبط