Laravel’de .env Dosyası Nedir, Nasıl Ayarlanır?

özgür BAYRAM16 Haziran 2026, 21:00

0 54 6 dakika okuma süresi

Laravel’de .env Dosyası Nedir, Nasıl Ayarlanır?

Laravel’de .env dosyası, uygulamanın çalıştığı ortama göre değişen ayarları tek bir yerde toplayan basit bir metin dosyasıdır. Veritabanı bağlantı bilgileri, uygulama anahtarı, e-posta sunucusu ayarları, ödeme sağlayıcısı ve yapay zekâ API anahtarları gibi gizli bilgiler genellikle burada tutulur. Aynı kod yerel bilgisayarınızda, test sunucusunda ve canlı ortamda farklı ayarlarla çalışabilsin diye bu değerler koddan ayrılır. Dosyaya parola ve API anahtarları konduğu için .env dosyası asla Git deposuna ve herkese açık web dizinine girmemelidir. Bu rehberde .env dosyasının yapısını, en önemli ayarları, yapılandırma önbelleğiyle ilişkisini, güvenlik önlemlerini ve sık karşılaşılan hataları adım adım ele alıyoruz.

Table of Contents

.env dosyası nasıl çalışır?

Laravel uygulama başlarken .env dosyasındaki ANAHTAR=değer satırlarını okuyarak ortam değişkenlerine yükler. Ancak uygulama kodunuz bu değerleri doğrudan okumamalıdır. Doğru akış şöyledir:

.env → config → uygulama — env() yalnızca config dosyalarında kullanılmalı.

.env dosyası ortam değişkenlerini tanımlar: MAIL_HOST=smtp.ornek.com
config dizinindeki yapılandırma dosyaları bu değerleri env() fonksiyonuyla okur ve varsayılan değer belirler: 'host' => env('MAIL_HOST', '127.0.0.1')
Uygulama kodu ayarlara her zaman config() fonksiyonuyla erişir: config('mail.mailers.smtp.host')

Bu ayrımın önemli bir nedeni var: canlı ortamda php artisan config:cache komutu çalıştırıldığında tüm yapılandırma tek bir önbellek dosyasında birleştirilir ve .env dosyası artık okunmaz. Bu durumda uygulama kodunun içinde doğrudan env() çağrısı yapan satırlar null döndürür. env() fonksiyonunu yalnızca config dosyalarında kullanmak, bu tür sinsi hataları önler.

Temel ayarlar

Uygulama ayarları

APP_NAME: Uygulamanın adı; e-postalarda ve bildirimlerde kullanılır.
APP_ENV: Ortam adı: local, staging veya production. Bazı paketler ve Laravel’in kendisi bu değere göre farklı davranır.
APP_KEY: Oturumların, çerezlerin ve şifrelenmiş verilerin şifrelenmesinde kullanılan anahtar. php artisan key:generate ile üretilir. Canlı ortamda değiştirilirse mevcut oturumlar geçersiz olur ve bu anahtarla şifrelenmiş veriler çözülemez.
APP_DEBUG: Hata ayrıntılarının ekranda gösterilip gösterilmeyeceği. Canlı ortamda mutlaka false olmalıdır.
APP_URL: Uygulamanın tam adresi. Komut satırından üretilen bağlantılar, e-postalardaki URL’ler ve dosya adresleri bu değeri kullanır; https:// ile ve doğru alan adıyla yazılmalıdır.

Veritabanı ayarları

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=uygulama
DB_USERNAME=uygulama_kullanici
DB_PASSWORD="karmaşık#parola!"

Paylaşımlı hostingde veritabanı ve kullanıcı adları genellikle cPanel kullanıcı adıyla ön eklidir (kullanici_uygulama gibi). Parolada boşluk, # veya = gibi özel karakterler varsa değeri çift tırnak içine alın; # karakteri tırnaksız yazılırsa satırın geri kalanı yorum olarak algılanır. Veritabanı bağlantı sorunları için PDO connection refused rehberimize bakabilirsiniz.

Diğer yaygın ayarlar

Önbellek, oturum ve kuyruk sürücüleri: CACHE_STORE, SESSION_DRIVER, QUEUE_CONNECTION (değişken adları Laravel sürümüne göre değişebilir; kendi sürümünüzün .env.example dosyasına bakın).
E-posta: MAIL_MAILER, MAIL_HOST, MAIL_PORT, MAIL_USERNAME, MAIL_PASSWORD, MAIL_FROM_ADDRESS. Ayrıntılar Laravel Mail SMTP rehberimizde.
Log: LOG_CHANNEL ve LOG_LEVEL; canlıda debug seviyesinde bırakmayın.
Üçüncü taraf servisler: Ödeme sağlayıcısı, harita, yapay zekâ ve bulut depolama anahtarları.

.env.example: paylaşılabilir şablon

Gerçek sırları içermeyen bir .env.example dosyası, projeye yeni katılan geliştiricilere veya yeni bir sunucuya kurulum yapacak kişiye hangi değişkenlerin gerektiğini gösterir. Bu dosya Git’e eklenir; içinde değişken adları ve güvenli örnek değerler bulunur:

APP_ENV=local
APP_DEBUG=true
APP_KEY=
DB_DATABASE=uygulama
DB_USERNAME=
DB_PASSWORD=
OPENAI_API_KEY=

Uygulamaya yeni bir ortam değişkeni eklediğinizde .env.example dosyasını da güncellemeyi alışkanlık haline getirin. Aksi halde yeni bir ortama kurulum yapılırken eksik değişken nedeniyle uygulama beklenmedik şekilde davranır.

.env dosyası güvenlik kontrolü — Kurulumdan sonra /.env adresinin 403/404 verdiğini test edin.

Güvenlik: .env dosyasını korumak

Git’e eklemeyin: Laravel’in varsayılan .gitignore dosyası .env dosyasını hariç tutar; bu satırın silinmediğinden emin olun. Yanlışlıkla eklenmiş bir .env dosyası sonradan silinse bile Git geçmişinde kalır; bu durumda içindeki tüm parola ve anahtarları değiştirmeniz gerekir.
Web kök dizinini doğru ayarlayın: Laravel’de web sunucusunun kök dizini public klasörü olmalıdır. Paylaşımlı hostingde proje dosyalarının tamamını public_html içine koymak, https://alanadi.com/.env adresinden dosyanın indirilmesine yol açabilir. Bu, sık görülen ve ciddi bir veri sızıntısı nedenidir.
Dosya izinleri: .env dosyası yalnızca uygulama kullanıcısı tarafından okunabilir olmalıdır (600 veya 640). Ayrıntılar için dosya izinleri rehberimize bakabilirsiniz.
Debug modunu kapatın: APP_DEBUG=true canlıda açık kalırsa hata sayfaları ortam değişkenlerini ve yapılandırma bilgilerini ziyaretçilere gösterebilir.
Şifreli ortam dosyası: Ekip içinde ortam dosyasını güvenli paylaşmak gerekiyorsa Laravel’in php artisan env:encrypt ve env:decrypt komutları dosyayı şifreleyerek depoya eklemenize izin verir; şifre çözme anahtarı ayrı ve güvenli bir kanaldan paylaşılmalıdır.

Yapılandırma önbelleği ve .env değişiklikleri

Canlı ortamda performans için php artisan config:cache çalıştırmak önerilir. Ancak bu komuttan sonra .env dosyasında yaptığınız değişiklikler, önbellek yeniden oluşturulana kadar uygulamaya yansımaz. Bu, “ayarı değiştirdim ama hiçbir şey olmadı” şikâyetlerinin en yaygın nedenidir.

.env değişikliğinden sonra php artisan config:cache komutunu tekrar çalıştırın veya önbelleği php artisan config:clear ile temizleyin.
Kuyruk işçileri (queue worker) uzun süre çalışan süreçlerdir ve yapılandırmayı başlarken yükler; değişiklikten sonra php artisan queue:restart ile yeniden başlatın.
Dağıtım (deploy) betiklerinize önbellek yenileme adımlarını ekleyin.

Önbellekle ilgili hataların ayrıntıları için Laravel config cache hatası rehberimize göz atabilirsiniz.

Sık karşılaşılan hatalar

“No application encryption key has been specified”: APP_KEY boş. php artisan key:generate komutunu çalıştırın.
Değer okunmuyor: Değişken adı yanlış yazılmış, değer tırnak hatası içeriyor veya yapılandırma önbelleği güncel değil.
Parolanın bir kısmı kayboluyor: Parolada # veya boşluk var ve değer tırnak içine alınmamış.
Yanlış ortam: Sunucuda APP_ENV=local kalmış; bazı paketler geliştirme davranışına geçer.
E-postalardaki bağlantılar yanlış: APP_URL hâlâ http://localhost değerinde.

Ortamlara göre örnek yapılandırma

Aynı uygulamanın farklı ortamlardaki .env değerleri, ortamın amacına göre bilinçli olarak farklılaşmalıdır. Aşağıdaki karşılaştırma, tipik bir projede hangi değerlerin nasıl ayarlanması gerektiğini gösterir:

Yerel geliştirme: APP_ENV=local, APP_DEBUG=true, LOG_LEVEL=debug. E-postalar gerçek kullanıcılara gitmemesi için MAIL_MAILER=log ile log dosyasına yazılır veya yerel bir test posta sunucusuna yönlendirilir. Ödeme sağlayıcıları test anahtarlarıyla kullanılır.
Test / staging: APP_ENV=staging, APP_DEBUG=false. Canlı ortama mümkün olduğunca benzer olmalı ama ayrı veritabanı, ayrı API anahtarları ve test ödeme hesapları kullanmalıdır. Arama motorlarına kapalı tutulmalı ve erişim parola ile korunmalıdır.
Canlı ortam: APP_ENV=production, APP_DEBUG=false, LOG_LEVEL=warning veya error. Gerçek SMTP sunucusu, canlı ödeme anahtarları ve https:// ile başlayan APP_URL.

Test ortamında canlı veritabanı veya canlı ödeme anahtarı kullanmak, test sırasında gerçek müşterilere e-posta gönderilmesi veya gerçek ödeme alınması gibi ciddi sonuçlar doğurabilir. Her ortamın kendi kaynaklarını kullandığından emin olmak için ortam değişkenlerini kurulum kontrol listesinin bir parçası yapın.

Paylaşımlı hostingde .env yönetimi

Laravel projelerini paylaşımlı hostinge yüklerken .env dosyasıyla ilgili sorunların çoğu dizin yapısından kaynaklanır. Güvenli bir düzen şöyledir: proje dosyalarının tamamı (app, config, .env, vendor vb.) public_html dışında, örneğin /home/kullanici/laravel-uygulama dizininde durur; yalnızca public klasörünün içeriği public_html içine konur veya alan adının belge kökü doğrudan public klasörüne yönlendirilir. Bu düzende .env dosyası web üzerinden hiçbir şekilde erişilemez.

Belge kökünü değiştiremediğiniz durumlarda bile .env dosyasını public_html içine koymak yerine yukarıdaki düzeni index.php içindeki yolları güncelleyerek uygulayın. Kurulumdan sonra tarayıcıda https://alanadi.com/.env adresini açıp 404 veya 403 aldığınızı mutlaka doğrulayın. Ayrıntılı kurulum adımları için Laravel cPanel yükleme rehberimize bakabilirsiniz.

Paylaşımlı hostingde SSH erişimi yoksa php artisan komutlarını çalıştırmak zorlaşır. Bu durumda yapılandırma önbelleğini yerelde oluşturup yüklemek yerine (önbellek dosyası yerel yolları içerebilir) önbelleği hiç kullanmamak veya hosting panelindeki terminal özelliğini kullanmak daha güvenlidir.

Sırları .env dışında yönetmek

Küçük ve orta ölçekli projelerde sırları .env dosyasında tutmak yeterlidir. Ekip büyüdükçe ve sunucu sayısı arttıkça şu ihtiyaçlar ortaya çıkar: sırların merkezi bir yerden yönetilmesi, erişim kayıtlarının tutulması ve anahtarların düzenli olarak değiştirilmesi. Bulut sağlayıcılarının sır yönetimi servisleri veya dağıtım platformlarının ortam değişkeni yönetimi bu ihtiyaçlara cevap verir. Hangi yöntemi seçerseniz seçin, şu ilkeler geçerlidir:

Her sır yalnızca ihtiyaç duyan ortamda bulunmalıdır.
Sırlar düzenli aralıklarla ve bir çalışan ekipten ayrıldığında değiştirilmelidir.
Sırlar sohbet uygulamalarında, e-postalarda veya hata raporlarında paylaşılmamalıdır.
Bir sırrın sızdığından şüphelenildiğinde önce sır iptal edilmeli, sonra nasıl sızdığı araştırılmalıdır.

Ortam değişkenlerini doğrulamak

Eksik veya hatalı bir ortam değişkeni, uygulamanın ancak ilgili özellik kullanıldığında hata vermesine yol açar: örneğin e-posta ayarı eksikse sorun ilk parola sıfırlama isteğinde ortaya çıkar. Bu tür sürprizleri önlemek için uygulama başlarken kritik değişkenlerin varlığını kontrol edebilirsiniz. Bir servis sağlayıcıda config('services.odeme.anahtar') gibi zorunlu değerlerin boş olup olmadığını kontrol edip boşsa açık bir hata mesajıyla uygulamayı durdurmak, sorunu dağıtım anında görünür kılar. Dağıtım betiğinize de .env dosyasının varlığını ve APP_KEY, APP_ENV, APP_DEBUG değerlerini kontrol eden basit bir adım eklemek, yanlış yapılandırmayla canlıya çıkmayı önler.

Sıkça Sorulan Sorular

.env dosyası projede görünmüyor, neden?

Nokta ile başlayan dosyalar birçok dosya yöneticisinde ve FTP istemcisinde gizli dosya olarak kabul edilir. “Gizli dosyaları göster” seçeneğini açın. Dosya gerçekten yoksa .env.example dosyasını kopyalayıp .env olarak adlandırın ve değerleri doldurun.

Canlı sunucuda .env yerine gerçek ortam değişkenleri kullanabilir miyim?

Evet. Sunucu veya barındırma platformu ortam değişkenlerini doğrudan tanımlıyorsa Laravel bunları da okur. Konteyner tabanlı ortamlarda bu yaygın bir yöntemdir.

APP_KEY’i değiştirmek güvenli mi?

Anahtar sızdıysa değiştirilmelidir; ancak değiştirildiğinde mevcut oturumlar sonlanır ve eski anahtarla şifrelenmiş veriler çözülemez. Laravel’in önceki anahtarları tanımlamaya izin veren yapılandırması geçişi kolaylaştırır.

Farklı ortamlar için birden fazla .env dosyası kullanılabilir mi?

Laravel APP_ENV değerine göre .env.staging gibi dosyaları yükleyebilir. Ancak çoğu projede her sunucuda tek bir .env dosyası tutmak daha sade ve hataya daha az açık bir yöntemdir.

.env dosyasında yorum satırı kullanabilir miyim?

Evet, # ile başlayan satırlar yorum olarak kabul edilir. Değişkenleri gruplar halinde düzenleyip açıklama eklemek dosyanın okunabilirliğini artırır.

Bir değişkeni başka bir değişkenin değeriyle tanımlayabilir miyim?

Evet, MAIL_FROM_NAME="${APP_NAME}" gibi bir sözdizimiyle başka bir değişkenin değeri kullanılabilir. Bu, aynı bilgiyi birden fazla yerde tekrar yazmayı önler.