فایل .env در Laravel — راهنمای کامل تنظیمات محیط local و production

فایل .env نقشه محرمانه محیط اجرای Laravel است: دیتابیس کجاست؟ کش روی Redis است یا file؟ ایمیل واقعاً ارسال شود یا log؟ یک خط اشتباه — مثلاً APP_DEBUG=true روی production — می‌تواند کل اپلیکیشن را در معرض نمایش stack trace قرار دهد. این راهنما بر اساس پروژه‌هایی است که روی XAMPP local شروع و روی Ubuntu + Nginx deploy شده‌اند.

چرا .env جدا از config است؟

فایل‌های config/*.php از env('KEY') مقدار می‌خوانند. کد یکسان در همه محیط‌ها؛ فقط .env عوض می‌شود. در production بعد از deploy باید php artisan config:cache بزنید. بعد از آن Laravel دیگر فایل .env را نمی‌خواند و env() بیرون از فایل‌های config مقدار null برمی‌گرداند؛ به همین دلیل در کد برنامه همیشه از config('app.name') استفاده کنید، نه env('APP_NAME').

متغیرهای حیاتی APP_*

APP_NAME="My App"
APP_ENV=local
APP_KEY=base64:...
APP_DEBUG=true
APP_URL=http://127.0.0.1:8000
APP_LOCALE=fa
APP_FALLBACK_LOCALE=en

APP_KEY برای رمزنگاری session، cookie و داده‌های encrypt‌شده استفاده می‌شود. در Laravel 12 دستور composer create-project آن را خودکار می‌سازد؛ اگر پروژه را از Git کلون کرده‌اید، php artisan key:generate را اجرا کنید. بدون آن Laravel خطای «No application encryption key» می‌دهد.

APP_DEBUG روی local=true، روی production حتماً false. OWASP و چک‌لیست امنیت هر دو تأکید دارند.

APP_ENV چه مقادیری می‌گیرد؟

APP_ENV فقط نام محیط است: معمولاً local برای سیستم توسعه، staging برای سرور تست، production برای سرور اصلی و testing هنگام اجرای تست‌ها (که phpunit.xml تنظیمش می‌کند). در کد با app()->environment('local') یا App::isProduction() آن را بررسی کنید و با php artisan about محیط فعلی، وضعیت debug و کش‌ها را یک‌جا ببینید. APP_ENV=local خودش debug را روشن نمی‌کند؛ نمایش خطا فقط به APP_DEBUG بستگی دارد.

timezone در Laravel 12

در اسکلت Laravel 11 و 12، مقدار timezone مستقیم در config/app.php روی 'UTC' نوشته شده و از .env خوانده نمی‌شود؛ پس اضافه کردن APP_TIMEZONE=Asia/Tehran به .env به‌تنهایی اثری ندارد. اگر می‌خواهید timezone از .env بیاید، در config/app.php بنویسید 'timezone' => env('APP_TIMEZONE', 'UTC') و بعد مقدار را در .env تنظیم کنید. بسیاری از تیم‌ها ترجیح می‌دهند زمان را در دیتابیس به UTC نگه دارند و فقط هنگام نمایش به وقت تهران تبدیل کنند.

تنظیمات دیتابیس

پروژه تازه Laravel 12 به‌صورت پیش‌فرض با DB_CONNECTION=sqlite و فایل database/database.sqlite ساخته می‌شود. برای MySQL یا MariaDB (مثلاً در XAMPP) مقادیر را این‌طور تغییر دهید:

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

# بازگشت به SQLite پیش‌فرض:
# DB_CONNECTION=sqlite
# (بدون DB_DATABASE، فایل database/database.sqlite استفاده می‌شود)

برای charset فارسی، migrationها utf8mb4 باشند. مقایسه MySQL و MariaDB: مقاله جداگانه.

کش، صف و session

در Laravel 11 و 12 پیش‌فرض هر سه روی database است (جدول‌هایشان با migrationهای پیش‌فرض ساخته می‌شوند). روی سیستم توسعه، file هم برای کش و session کافی است:

CACHE_STORE=database
QUEUE_CONNECTION=database
SESSION_DRIVER=database
SESSION_LIFETIME=120

# production پیشنهادی:
# CACHE_STORE=redis
# QUEUE_CONNECTION=redis
# SESSION_DRIVER=redis

Redis را در بهینه‌سازی کش پوشش داده‌ام. برای شروع، database queue و file cache کافی است.

Mail

MAIL_MAILER=log
MAIL_FROM_ADDRESS="hello@example.com"
MAIL_FROM_NAME="${APP_NAME}"

روی local از log استفاده کنید تا ایمیل در storage/logs بیفتد. production: smtp یا سرویس transactional.

فایل .env.example

همیشه در Git باشد؛ بدون secret. هر متغیر جدیدی که به .env اضافه می‌کنید، در .env.example با مقدار خالی یا placeholder ثبت کنید — برای onboarding تیم.

اشتباهات رایج

• commit کردن .env — هرگز
• استفاده از env() مستقیم در کد application (فقط در config)
• فراموش کردن config:cache بعد از تغییر env در production
• APP_URL اشتباه — لینک‌های mail و storage خراب می‌شود
• رمز دیتابیس خالی روی سرور عمومی

محیط‌های چندگانه

می‌توانید .env.staging داشته باشید و در deploy کپی کنید. اگر APP_ENV به‌عنوان متغیر محیطی واقعی سرور تنظیم شده باشد یا artisan را با --env=staging اجرا کنید، Laravel اگر فایل .env.staging وجود داشته باشد آن را به‌جای .env بارگذاری می‌کند. سرویس‌هایی مثل Laravel Forge، Vapor و Laravel Cloud متغیرها را از پنل خودشان مدیریت می‌کنند. برای CI، GitHub Secrets به .env تبدیل می‌شود. اگر لازم است فایل env را در مخزن نگه دارید، فقط نسخه رمزشده آن را با php artisan env:encrypt commit کنید و روی سرور با env:decrypt باز کنید.

امنیت

permission فایل .env روی سرور ۶۰۰. در shared hosting مطمئن شوید از وب قابل خواندن نیست و Document Root روی پوشه public است. عوض کردن APP_KEY باعث می‌شود sessionها و داده‌های رمزشده با کلید قبلی دیگر خوانده نشوند؛ در Laravel 11 و 12 می‌توانید کلید قبلی را در APP_PREVIOUS_KEYS (با کاما جدا) نگه دارید تا در دوره انتقال، داده‌های قدیمی هنوز رمزگشایی شوند.

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

بعد از تغییر .env چه کنم؟

روی local معمولاً تغییر بلافاصله اعمال می‌شود. اگر قبلاً config:cache زده‌اید، php artisan config:clear را اجرا کنید؛ روی production بعد از هر تغییر دوباره php artisan config:cache بزنید و workerهای صف را با php artisan queue:restart ری‌استارت کنید. مراحل کامل deploy در Deploy Laravel روی Ubuntu آمده است.

QUEUE_CONNECTION=sync یعنی چه؟

jobها همان لحظه و داخل همان درخواست اجرا می‌شوند و worker لازم نیست — برای توسعه و تست مناسب است، نه برای production.

MAIL_MAILER=log چه می‌کند؟

ایمیل واقعاً ارسال نمی‌شود و متن آن در لاگ نوشته می‌شود؛ برای local امن‌ترین انتخاب است.

SQLite برای production مناسب است؟

برای اپلیکیشن ساده با ترافیک کم گاهی بله؛ برای نوشتن هم‌زمان زیاد، MySQL، MariaDB یا PostgreSQL انتخاب مطمئن‌تری است.

جمع‌بندی

.env قرارداد بین کد و infrastructure است. local را ساده نگه دارید؛ production را با Redis، debug خاموش و backup منظم. بعد از تنظیم env، اولین route را بزنید.

نیاز به setup سرور دارید؟ تماس بگیرید.