OPTIONS 프리플라이트가 언제 발생하고 어떤 헤더를 검사하는지 단계별로 시각화합니다. Access-Control-Request-Method/Headers와 서버 응답 헤더의 대응 관계를 확인하세요.
시나리오 프리셋
요청 — 브라우저(페이지) 쪽
Method
Content-Type
커스텀 헤더
Access-Control-Request-Headers: content-type, x-api-key
응답 — 서버가 보내는 헤더
Access-Control-Allow-Origin
Access-Control-Allow-Methods
Access-Control-Allow-Headers
요청에 필요한 헤더 + 자주 쓰는 값 — 클릭으로 토글
브라우저 처리 단계
페이지에서 fetch 요청 발생
단순 요청이 아님 — OPTIONS 프리플라이트 필요
OPTIONS 프리플라이트 요청 전송
OPTIONS /data HTTP/1.1 Origin: https://myapp.example.com Access-Control-Request-Method: POST Access-Control-Request-Headers: content-type, x-api-key
서버의 프리플라이트 응답 도착
HTTP/1.1 204 No Content Access-Control-Allow-Origin: https://myapp.example.com Access-Control-Allow-Methods: GET, POST, PUT Access-Control-Allow-Headers: content-type, x-api-key
Allow-Origin이 출처와 일치 — 통과
요청 메서드가 Allow-Methods에 포함 — 통과
요청 헤더가 Allow-Headers에 모두 포함 — 통과
credentials 미사용 — 검사 생략
프리플라이트 통과 — 본 요청으로 진행
본 요청 전송
POST /data HTTP/1.1 Origin: https://myapp.example.com Content-Type: application/json X-Api-Key: s3cr3t
서버의 본 응답 도착
HTTP/1.1 200 OK
Access-Control-Allow-Origin: https://myapp.example.com
{"status": "ok"}Allow-Origin이 출처와 일치 — 통과
응답이 JavaScript에 전달됨 — 성공
브라우저 콘솔
▸ 응답이 JavaScript 코드에 정상 전달됐습니다.
값을 바꾸면 아래 단계가 즉시 다시 계산됩니다. 'credentials + *' 시나리오에서 와일드카드가 왜 막히는지 확인해 보세요.
요청이 '단순 요청' 조건을 벗어나면 브라우저는 본 요청 전에 OPTIONS 메서드로 프리플라이트를 보냅니다. Access-Control-Request-Method로 '이 메서드를 쓸 예정', Access-Control-Request-Headers로 '이 헤더를 붙일 예정'이라고 서버에 미리 확인하는 절차입니다.
서버는 세 가지 헤더로 응답해야 합니다. Access-Control-Allow-Origin(출처 허가), Access-Control-Allow-Methods(메서드 목록), Access-Control-Allow-Headers(헤더 목록). 셋 중 하나라도 요청과 맞지 않으면 브라우저는 본 요청을 아예 보내지 않고 실패 처리합니다.
실무 팁: 프리플라이트는 매 요청마다 발생해 지연이 됩니다. Access-Control-Max-Age를 응답에 넣으면 브라우저가 그 결과를 캐시해 같은 프리플라이트를 생략합니다. PUT/DELETE나 Authorization 헤더를 쓰는 API라면 반드시 설정을 권합니다. CORS 시뮬레이터에서 다른 시나리오도 같은 설정으로 비교해 보세요.