فایل .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 بزنید — آن‌وقت مستقیم env() در runtime کار نمی‌کند مگر در config files.

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

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

APP_KEY با php artisan key:generate ساخته می‌شود — برای encryption session و cookie. بدون آن Laravel خطا می‌دهد.

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

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

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=/absolute/path/database/database.sqlite

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

کش، صف و session

CACHE_STORE=file
QUEUE_CONNECTION=database
SESSION_DRIVER=file
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 کپی کنید. Laravel Vapor/Herd env را از پنل می‌گیرند. برای CI، GitHub Secrets به .env تبدیل می‌شود.

امنیت

permission فایل .env روی سرور ۶۰۰. در shared hosting مطمئن شوید از وب قابل خواندن نیست. rotate کردن APP_KEY sessionهای قبلی را باطل می‌کند — با برنامه‌ریزی انجام دهید.

جمع‌بندی

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

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