การตรวจสอบ YAML Docker Compose: 10 ข้อผิดพลาดไวยากรณ์ที่พบบ่อยและวิธีแก้ไข

ไฟล์ YAML ของ Docker Compose ดูง่าย — จนกว่าจะพัง ช่องว่างผิดที่ การเยื้องผิด หรือตัวอักษรพิเศษไม่ใส่เครื่องหมายคำพูด ทำให้เกิดข้อความแสดงข้อผิดพลาดที่อ่านยาก นี่คือ 10 ความผิดพลาดที่พบบ่อยที่สุด และวิธีแก้ไข

ตรวจสอบ YAML ด้วย JSON-YAML Converter ของเรา →

ข้อผิดพลาด 1: ใช้ Tab แทนช่องว่าง

ข้อความข้อผิดพลาด:

yaml: line 5: found a tab character where an indentation space is expected

ปัญหา: YAML ไม่อนุญาตให้ใช้ Tab สำหรับการเยื้อง

การแก้ไข: แทนที่ Tab ทั้งหมดด้วยช่องว่าง (2 ช่องว่างต่อระดับ)

# BAD (tabs - invisible but breaks YAML)
services:
	web:
		image: nginx

# GOOD (2 spaces)
services:
  web:
    image: nginx

เคล็ดลับตัวแก้ไข: เปิด "Render Whitespace" ในตัวแก้ไข

ข้อผิดพลาด 2: การเยื้องไม่สอดคล้องกัน

ข้อความข้อผิดพลาด:

yaml: line 8: mapping values are not allowed in this context

ปัญหา: ผสมระดับการเยื้อง (2 ช่องว่างที่นี่ 4 ที่นั่น)

# BAD (inconsistent: 2 spaces then 4 spaces)
services:
  web:
      image: nginx     # 4 spaces - inconsistent!
      ports:
        - "80:80"

# GOOD (consistent 2 spaces)
services:
  web:
    image: nginx       # 2 spaces - consistent
    ports:
      - "80:80"

ข้อผิดพลาด 3: ตัวอักษรพิเศษไม่ใส่เครื่องหมายคำพูด

ข้อความข้อผิดพลาด:

yaml: line 6: did not find expected key

ปัญหา: YAML ตีความโคลอน แฮช และวงเล็บปีกกาเป็นพิเศษ ต้องใส่เครื่องหมายคำพูด

# BAD
services:
  web:
    environment:
      - DATABASE_URL=postgres://user:pass@db:5432/mydb  # colon in value!
      - APP_TITLE=My App: The Best                       # colon in value!

# GOOD (quote values with special characters)
services:
  web:
    environment:
      - "DATABASE_URL=postgres://user:pass@db:5432/mydb"
      - "APP_TITLE=My App: The Best"

ตัวอักษรที่ต้องใส่เครื่องหมายคำพูด: : { } [ ] , & * # ? | - < > = ! % @

ข้อผิดพลาด 4: รูปแบบการแมปพอร์ตผิด

ข้อความข้อผิดพลาด:

services.web.ports contains an invalid type, it should be a number, or an object

ปัญหา: YAML อาจตีความ 80:80 โดยไม่ใส่เครื่องหมายคำพูดเป็นฐาน 60

# RISKY (YAML may interpret as base-60)
services:
  web:
    ports:
      - 80:80        # Works but risky
      - 5432:5432    # May cause issues

# SAFE (always quote port mappings)
services:
  web:
    ports:
      - "80:80"
      - "5432:5432"
      - "127.0.0.1:3000:3000"

ข้อผิดพลาด 5: ไม่มีหรือผิดคีย์ version

ข้อความข้อผิดพลาด:

(root) Additional property version is not allowed

ปัญหา: Docker Compose v2 ไม่ต้องการคีย์ version อีกต่อไป

# OUTDATED (Docker Compose v1 format)
version: "3.8"
services:
  web:
    image: nginx

# CURRENT (Docker Compose v2 - no version needed)
services:
  web:
    image: nginx

ใช้ docker compose (v2): ลบ version ใช้ docker-compose (v1): เก็บไว้

ข้อผิดพลาด 6: ตัวแปรแวดล้อม mapping vs list

ข้อความข้อผิดพลาด:

services.web.environment must be a mapping or an array

ปัญหา: ผสมไวยากรณ์ mapping และ list สำหรับตัวแปรแวดล้อม

# Format A: List (with dashes)
services:
  web:
    environment:
      - NODE_ENV=production
      - PORT=3000

# Format B: Mapping (key: value)
services:
  web:
    environment:
      NODE_ENV: production
      PORT: 3000

# BAD: Mixing both formats
services:
  web:
    environment:
      NODE_ENV: production
      - PORT=3000          # ERROR: mixing formats!

ข้อผิดพลาด 7: ค่าบูลีนไม่ใส่เครื่องหมายคำพูด

ข้อความข้อผิดพลาด: ไม่เกิดข้อผิดพลาด แต่พฤติกรรมไม่ตรงตามที่คาดไว้

ปัญหา: YAML ตีความ yes, no, true, false, on, off เป็นบูลีน

# BAD (YAML converts to boolean true/false)
services:
  web:
    environment:
      FEATURE_FLAG: yes       # becomes boolean true, not string "yes"
      DEBUG: on               # becomes boolean true
      COUNTRY: NO             # becomes boolean false (Norway code!)

# GOOD (quote string values)
services:
  web:
    environment:
      FEATURE_FLAG: "yes"
      DEBUG: "on"
      COUNTRY: "NO"

ข้อผิดพลาด 8: คีย์ซ้ำ

ข้อความข้อผิดพลาด: มักไม่เกิดข้อผิดพลาด — ค่าที่สองจะเขียนทับค่าแรก

# BAD (duplicate 'ports' key - second one silently wins)
services:
  web:
    image: nginx
    ports:
      - "80:80"
    environment:
      - NODE_ENV=production
    ports:                    # DUPLICATE! This replaces the first ports
      - "443:443"

# GOOD (combine under single key)
services:
  web:
    image: nginx
    ports:
      - "80:80"
      - "443:443"
    environment:
      - NODE_ENV=production

ข้อผิดพลาด 9: ปัญหา path ของ volumes

ข้อความข้อผิดพลาด:

services.web.volumes contains an invalid type

ปัญหา: Path ของ Windows ที่มี backslash ต้องใส่เครื่องหมายคำพูด

# BAD (Windows paths without quotes)
services:
  web:
    volumes:
      - C:\Users\me\app:/app     # Backslashes cause issues

# GOOD (use forward slashes or quotes)
services:
  web:
    volumes:
      - "./app:/app"
      - "/home/user/data:/data"
      - "C:/Users/me/app:/app"      # Forward slashes on Windows

ข้อผิดพลาด 10: YAML anchors ใช้ผิด

ข้อความข้อผิดพลาด:

yaml: unknown anchor 'common'

ปัญหา: อ้างอิง anchor (*name) ก่อนกำหนด (&name)

# BAD (reference before definition)
services:
  web:
    <<: *common          # ERROR: 'common' not defined yet

x-common: &common
  restart: always

# GOOD (define anchor first, then reference)
x-common: &common
  restart: always
  logging:
    driver: json-file

services:
  web:
    <<: *common
    image: nginx
  api:
    <<: *common
    image: node:20

รายการตรวจสอบอย่างรวดเร็ว

ก่อน docker compose up ให้ตรวจสอบ:

1. รัน docker compose config เพื่อตรวจสอบไวยากรณ์
2. ตรวจสอบ tab: grep -P '\t' docker-compose.yml
3. ใส่เครื่องหมายคำพูดกับ mapping ของพอร์ตทั้งหมด
4. ไม่มีคีย์ซ้ำในระดับเดียวกัน
5. ใส่เครื่องหมายคำพูดกับค่าที่มีตัวอักษรพิเศษ
6. การเยื้องสอดคล้องกัน (2 ช่องว่างแนะนำ)

ตรวจสอบ YAML ด้วย JSON-YAML Converter ของเรา →

จัดรูปแบบ JSON จาก "docker compose config" →