encodeURIComponent ile encodeURI Arasındaki Fark
JavaScript'te URL kodlamak için iki farklı fonksiyon vardır ve ikisi de çok benzer isimlere sahiptir: encodeURIComponent() ve encodeURI(). Bunları karıştırmak, en sık rastlanan URL kodlama hatasıdır ve genelde ya bozuk bir adres ya da kaybolan bir parametreyle sonuçlanır. Bu rehberde ikisi arasındaki farkı, hangisini ne zaman kullanmanız gerektiğini ve tipik hataları örneklerle gösteriyoruz.
encodeURIComponent ile encodeURI arasındaki temel fark nedir?
& = ? / : # gibi URL yapısını oluşturan karakterleri de kodlar. encodeURI() ise TAM bir URL'yi kodlar; adresin çalışması için gerekli olan : / ? # & = karakterlerini olduğu gibi bırakır. Tek bir parametre değeri için encodeURIComponent, tam bir adres için encodeURI kullanılmalıdır.
Bu tek cümle, aslında sorunun %90'ını çözer: sorunuz "bu benim TÜM adresim mi, yoksa adresin içine koyacağım TEK bir DEĞER mi?" Cevap "tüm adres" ise encodeURI, "tek bir değer" ise encodeURIComponent kullanın. Kendi metninizi hemen deneyerek görmek isterseniz encode aracını kullanabilirsiniz.
Hangi karakterler her fonksiyonda kodlanır?
A-Z a-z 0-9 - _ . ! ~ * ' ( ) ve ; / ? : @ & = + $ , # karakterlerini kodlamadan bırakır (URL yapısı için gereklidirler); geri kalan her şeyi (boşluk, Türkçe harf, emoji) kodlar. encodeURIComponent ise bu "yapı karakterlerinin" çoğunu (; / ? : @ & = + $ , #) DA kodlar — sadece A-Z a-z 0-9 - _ . ! ~ * ' ( ) dokunulmaz kalır.
| Karakter grubu | encodeURI() | encodeURIComponent() |
|---|---|---|
Harfler, rakamlar, - _ . ! ~ * ' ( ) | Kodlanmaz | Kodlanmaz |
; / ? : @ & = + $ , # | Kodlanmaz (URL yapısı) | Kodlanır |
Boşluk, Türkçe harf, emoji, % | Kodlanır | Kodlanır |
Kaynak: ECMAScript dil spesifikasyonu (encodeURI/encodeURIComponent tanımları) + RFC 3986.
Kod örnekleriyle karşılaştırma
Aynı girdiyi her iki fonksiyondan geçirdiğimizde sonuçların ne kadar farklılaştığını doğrudan görelim:
| Girdi | encodeURI() sonucu | encodeURIComponent() sonucu |
|---|---|---|
a&b=c | a&b=c (değişmez) | a%26b%3Dc |
https://x.com/a b?c=1 | https://x.com/a%20b?c=1 | https%3A%2F%2Fx.com%2Fa%20b%3Fc%3D1 |
İzmir, Türkiye | %C4%B0zmir,%20T%C3%BCrkiye | %C4%B0zmir%2C%20T%C3%BCrkiye |
İkinci satır, en çok karşılaşılan hatayı gösterir: https://x.com/a b?c=1 gibi TAM bir adresi encodeURIComponent ile kodlarsanız, :// ve ? de kodlanır ve ortaya çıkan metin artık geçerli bir URL DEĞİLDİR — tarayıcıya yapıştırılamaz, bir <a href> özniteliğine konamaz. Bu değer ancak BAŞKA bir URL'nin parametre değeri olarak kullanılabilir.
encodeURIComponent ile kodlayıp bir dış URL'nin query değerine gömersiniz (encodeURI değil, çünkü artık o bir DEĞERDİR); dış URL'nin kendisine ise dokunmazsınız. Bu ayrımı gözden kaçırmak, "geri dön" linklerinin en sık bozulma sebebidir.
İkisini de canlı dene
"Bileşen (encodeURIComponent)" ve "Tam URI (encodeURI)" modları arasında geçiş yaparak aynı metnin iki farklı sonucunu yan yana gör.
Encode Aracını Aç →Sık yapılan hata: yanlış fonksiyonu seçmek
encodeURI ile kodlamaktır. Değerin içinde & veya = varsa (örn. "ad=Ahmet&soyad=Yılmaz" gibi bir metin), bu karakterler encodeURI tarafından kodlanmadığı için sunucu bunları yeni parametrelerin başlangıcı sanır ve orijinal değer parçalanır.
Kullanıcı arama kutusuna
"C&A markası" yazdı. Bu metni yanlışlıkla encodeURI("C&A markası") ile kodlarsanız sonuç C&A%20markas%C4%B1 olur — & kodlanmadığı için sunucu bunu C adında bir parametre ve A markası adında YENİ bir parametre sanabilir. Doğrusu encodeURIComponent("C&A markası") kullanmaktır: C%26A%20markas%C4%B1.
Hangisini ne zaman kullanmalı? (pratik kural)
encodeURIComponent; kodlayacağınız şey zaten tam ve geçerli bir URL (yalnızca içindeki boşluk/Türkçe karakter gibi güvensiz kısımları temizlemek istiyorsanız) ise encodeURI kullanın. Şüphedeyseniz, %95 ihtimalle aradığınız encodeURIComponent'dır.
- Arama kutusu → query parametresi:
encodeURIComponent(değer, tam URL değil). - Kullanıcının girdiği tam bir web adresini normalize etme:
encodeURI(zaten bir URL). - Bir URL'yi başka bir URL'nin parametresine gömme (redirect linki):
encodeURIComponent(artık bir DEĞER). - Dosya adı, kullanıcı adı, e-posta gibi tekil bir alanı path'e ekleme:
encodeURIComponent.
Karşı işlem için decodeURIComponent() ve decodeURI() kullanılır; pratikte decode ederken hangisini seçtiğiniz genelde sonucu değiştirmez çünkü decode, encode sırasında hangi karakterin dokunulmadan bırakıldığına bağlı değildir. Bir query string'in tamamının nasıl ayrıştırıldığını görmek için query string rehberimize göz atabilirsiniz.
Sık sorulan sorular
encodeURIComponent nedir?
& = ? / : # gibi URL yapısını oluşturan karakterleri de kodlar; bu yüzden bir değerin içinde bu karakterler geçse bile güvenle kodlanır.encodeURI nedir?
: / ? # & = karakterlerini kodlamadan bırakır; sadece boşluk, Türkçe harf ve emoji gibi güvensiz karakterleri kodlar.encodeURIComponent ile encodeURI'yi karıştırırsam ne olur?
: / ? & = gibi karakterler de kodlanır ve adres çalışmaz bir metne döner. Bir değeri encodeURI ile kodlarsanız değerin içindeki & veya = kodlanmadan kalır ve parametre sınırları karışabilir.Hangi durumda hangisini kullanmalıyım?
decodeURIComponent ile decodeURI arasında fark var mı?
İlgili rehberler
encodeURI() ve encodeURIComponent() fonksiyonları doğrudan çalıştırılarak üretilip doğrulanmıştır. Kaynaklar: ECMAScript (ECMA-262) dil spesifikasyonu · RFC 3986 · MDN Web Docs. Son güncelleme: 17 Temmuz 2026. Yazı bilgilendirme amaçlıdır; üretim kodunuzda kullanmadan önce kendi ortamınızda test etmeniz önerilir.