docker-compose, Kubernetes ya da GitHub Actions dosyası yazanlar için: hangi hatayı araç yakalıyor, hangisini yalnızca bildiriyor.
docker-compose dosyasını kaydettiniz, komutu çalıştırdınız, hata verdi. Bir satır yukarı, bir satır aşağı bakıyorsunuz, her şey yerinde görünüyor. Sorun çoğu zaman gözle seçilemeyen bir şey: bir boşluk fazlası ya da bir sekme karakteri.
Bu yazıda 5 tipik YAML hatasını YAML Biçimlendirici'de denedik: hizasız girinti, sekme karakteri, no değerinin false olması, sekizlik sayı ve saat gibi görünen değer. Ardından yorumlu bir GitHub Actions dosyasıyla anchor içeren bir bloğu biçimlendirdik.
Kısaca
YAML neden girintiye bu kadar hassas?
YAML'de bir değerin hangi anahtara bağlı olduğunu süslü parantez ya da kapanış etiketi değil, satırın başındaki boşluk sayısı söyler. Bir kitabın fihristi gibi: alt başlığın hangi başlığa ait olduğu, kaç adım içeriden başladığından anlaşılır. Bir satır yanlış hizalanırsa fihrist bozulur ve okuyucu hangi bölümde olduğunu bilemez.
Sözdizimi kuralı küçük ama sonucu büyük: iki boşlukla yazılmış bir liste öğesi ile üç boşlukla yazılmış olanı birbirinden gözle ayırmak zordur. Bir de değerlerin nasıl okunacağı sorusu var; aynı dosyayı iki farklı okuyucu iki farklı anlayabilir. Bu yüzden aracın YAML sürümü seçimi (1.1 ve 1.2) yazının ikinci yarısında önemli.
Denedik: 5 hata, 5 mesaj
İlk denemede bir compose dosyası hazırladık. ports: altındaki ilk satırı 7 boşlukla, ikincisini 6 boşlukla yazdık:
services:
web:
image: nginx
ports:
- "8080:80"
- "8443:443"Araç kırmızı bir kutu açtı: "Bu belge okunamadı, biçimlendirilemiyor." Kutuda "6. satır, 1. sütun: Girinti yapısı bozuk" yazıyordu.
Denetim raporu dört madde saydı: değeri boş bırakılmış bir anahtar için bilgi, 6. satırda iki girinti hatası ve 7. sütunda bir de "Kapanmamış tırnak veya karakter" hatası. Son madde bizi yanıltabilir: asıl sorun hizalama, tırnak değil. İlk mesaja güvenin, sonrakileri aynı kökten çıkan yan etki olarak okuyun.
Hizayı düzelttiğimizde, yani ikinci satırı da aynı 6 boşluğa aldığımızda dosya sorunsuz biçimlendirildi ve girdi ile çıktı aynı uzunlukta (82 karakter) geldi:
services:
web:
image: nginx
ports:
- "8080:80"
- "8443:443"Sekme karakteri neden kabul edilmiyor?
İkinci denemede girintiyi boşluk yerine sekmeyle yazdık (web: satırına bir, image: satırına iki sekme). Araç "2. satır, 1. sütun: Girintide sekme karakteri var, YAML sekme kabul etmez" dedi ve sekme içeren her satırı ayrı ayrı listeledi.
Sekme ile boşluk ekranda aynı görünebilir; editörünüz sekmeyi dört boşluk gibi çizer. Hata mesajındaki satır ve sütun bu yüzden işe yarıyor: gözle ayıramadığınız şeyi size konumuyla gösteriyor. Çözüm editörünüzde sekmeyi boşluğa çevirmek.
Norveç sorunu: no neden false oluyor?
YAML 1.1'de tırnaksız yazılan yes, no, on ve off mantıksal değer sayılır. İsim "Norveç sorunu" oradan geliyor: ülke kodu olarak yazılan no, listeyi okuyan araçta false olur. Beş satırlık bir dosyayı iki sürümle JSON'a çevirdik:
ulke: no
izin: 0755
saat: 12:30
surum: 1.10
evet: yes| Değer | YAML 1.1 okuması | YAML 1.2 okuması |
|---|---|---|
| ulke: no | false | "no" (metin) |
| izin: 0755 | 493 (sekizlik sayı) | 755 (ondalık sayı) |
| saat: 12:30 | 750 (altmışlık tabanda sayı) | "12:30" (metin) |
| surum: 1.10 | 1.1 | 1.1 |
| evet: yes | true | "yes" (metin) |
Araç bunu önceden söylüyor: 1 tehlike ve 4 uyarı. Tehlike düzeyindeki madde 0755 için: "Bu değer YAML 1.1 ve 1.2 okuyucularında farklı anlaşılır". Aynı dosya, hangi aracın okuduğuna göre farklı bir yapılandırma olur.
1.10 satırında iki sürüm aynı sonucu verdi, ama sonuç yine de beklenmedik: sayı olarak okunan 1.10, sondaki sıfırını kaybedip 1.1 oldu. Sürüm numarasını dosyada sayı değil metin olarak tutmak istiyorsanız tırnak içine alın.
Aynı beş satırı bu kez değerleri çift tırnak içine alarak yazdık, sürümü yine 1.1 bıraktık. JSON çıktısında beşi de metin olarak geldi: "no", "0755", "12:30", "1.10" ve "yes". Uyarı ve tehlike maddesi de kalmadı. Yani tırnak, iki okuyucunun aynı şeyi anlamasını sağlayan en basit önlem; sürüm numaralarını ve ülke kodlarını tırnakla yazmak alışkanlık olabilir.
Yorumlar ve anchor'lar korunuyor mu?
Yorumlu bir GitHub Actions dosyası yapıştırdık. Araç "1 belge, 11 anahtar, 2 yorum" diye sayıp çıktıda 2 yorumun da durduğunu gösterdi:
# derleme akisi
name: derle
on:
push:
branches: [ main ] # yalniz main
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Test
run: |
npm ci
npm testTek fark, branches: [ main ] satırındaki üç boşluk, yorumdan önce tek boşluğa indi; yorumun kendisi aynen kaldı. Sayfa bu dosya için de bir uyarı verdi: on değeri YAML 1.1 okuyucusunda mantıksal, 1.2 okuyucusunda metin olarak okunabilir. GitHub Actions dosyalarında bu anahtar her zaman vardır; uyarıyı gördüğünüzde dosyayı bozmanız gerekmez, hangi okuyucunun kullandığını bilmeniz yeter.
Sonra anchor, alias ve birleştirme anahtarı içeren bir blok denedik:
varsayilan: &vars
bellek: 512m
yeniden: always
web:
<<: *vars
image: nginx
worker:
<<: *vars
bellek: 1gAraç "1 çapa, 2 takma ad" kullanıldığını bildirdi ve birleştirme anahtarı için iki uyarı verdi. JSON çıktısı sürüme göre değişti: YAML 1.1 seçiliyken web ve worker bloklarına varsayılan değerler kopyalandı ve worker'ın kendi bellek değeri (1g) üstün geldi. YAML 1.2 seçiliyken birleştirme yapılmadı, << anahtarı olduğu gibi çıktıya geçti.
Adım adım ve aracın sınırları
- Dosyayı sol kutuya yapıştırın ve hangi aracın okuyacağına göre YAML sürümünü seçin: Kubernetes ve Ansible için 1.1, diğerleri için 1.2.
- Kırmızı kutu varsa ilk mesajdaki satır ve sütuna gidin; sonrakiler çoğu zaman aynı kökten gelir.
- Sekme uyarısı varsa editörünüzde sekmeyi boşluğa çevirin.
- Tehlike ve uyarı maddelerini okuyun; no, 0755, 12:30 gibi değerleri gerekiyorsa tırnak içine alın.
- Çıktıyı kopyalayın ya da indirin. İsterseniz çıktı biçimini JSON'a alıp iki sürümün farkına bakın.
- Hatayı kendisi düzeltmiyor. Neyin, nerede bozuk olduğunu gösteriyor; dosyayı siz düzeltiyorsunuz.
- Aynı köke bağlı fazladan hata mesajı verebiliyor. Bizim girinti denememizde tırnak hatası buna örnek.
- Dosyanın çalışacağını garanti etmiyor. docker-compose ya da Actions'ın kendi kuralları (örneğin anahtar adları) ayrı bir konu.
- Yalnız beş değer türünü denedik. Büyük tamsayılar, özel tip etiketleri ve çok belgeli dosyaları bu yazıda denemedik.
Kontrol listesi
- YAML sürümü dosyayı okuyacak araca göre seçildi
- Girintide sekme karakteri kalmadı
- Kırmızı kutudaki ilk hata satırı düzeltildi
- no, yes, on, off ve 0755 gibi değerler kontrol edildi
- Sürüm numaraları gerekiyorsa tırnak içine alındı
- JSON çıktısında iki sürümün farkı bir kez gözden geçirildi
Araç dosyanızı düzeltmiyor; nerede, neden bozulduğunu satır ve sütunla gösteriyor. Kendi dosyanızla YAML Biçimlendirici'yi ücretsiz deneyebilirsiniz.
Bu denemeyi 29 Eylül 2026'da Chrome'da yaptık. Dosya içerikleri kurgusaldır.
Kaynaklar
Bahsedilen
- Belirtilmemiş
Temel Alınan Çalışma
- Belirtilmemiş
