사이트 오류 해결방법 문서

개요 및 원칙

• 표준 준수: 시맨틱 HTML, 올바른 문서 구조, 유효한 속성/값을 사용합니다.
• 접근성 우선: 키보드 내비게이션, 대체 텍스트, 적절한 ARIA 사용으로 모두에게 동작하게 합니다.
• 가시성 확보: 로깅, 에러 바운더리, 모니터링으로 문제가 보이게 합니다.
• 회귀 방지: 자동화 테스트와 릴리즈 체크리스트를 유지합니다.

일반 오류 유형과 빠른 진단

HTML/CSS 오류 해결

시맨틱 구조와 유효성

• 문서 구조: 헤딩(H1–H6)은 계층적으로 사용하고 스킵하지 않습니다.
• 대체 텍스트: 의미 있는 이미지에는 적절한 alt를 제공합니다.
• 양식 접근성: label은 for로 컨트롤과 연결하고 에러 메시지에 aria-live를 사용합니다.

레이아웃 깨짐 디버깅

• 컨테이너 크기: 부모 요소의 overflow와 position을 점검합니다.
• 그리드/플렉스: 최소 너비(min-width)와 축 정렬을 확인합니다.
• 반응형 단위: clamp(), minmax()로 급격한 변형을 줄입니다.

유효성 검사 포인트

• 중복 ID: 페이지 내 ID는 고유해야 합니다.
• 닫힘 태그: 모든 요소가 올바르게 닫혀야 합니다.
• 잘못된 속성: 지원되지 않는 속성/값을 제거하거나 대체합니다.

자바스크립트 및 런타임 오류 해결

콘솔/스택트레이스 해석

• 원인 라인: 스택 최상단의 사용자 코드 라인을 우선 확인합니다.
• 재현 시나리오: 최소 재현 케이스를 만들고 외부 의존성을 제거합니다.
• 소스맵: 프로덕션 번들에는 정확한 소스맵을 제공하세요.

// 위험: null 요소에 접근
// const node = document.querySelector('.target').textContent;

// 안전: 존재 확인 후 접근
const node = document.querySelector('.target');
if (node) {
  node.textContent = '준비 완료';
} else {
  console.warn('요소(.target)를 찾을 수 없습니다.');
}
        

에러 경계와 복구

• UI 에러 경계: 프런트엔드 프레임워크의 에러 바운더리로 사용자 영향 최소화.
• 재시도 정책: 지수 백오프와 Retry-After 헤더 고려.
• 로깅: 민감정보를 제외하고 에러 ID, 사용자 환경, 스택을 수집.

async function fetchWithRetry(url, opts = {}, { retries = 3, backoff = 500 } = {}) {
  let lastErr;
  for (let i = 0; i < retries; i++) {
    try {
      const res = await fetch(url, opts);
      if (!res.ok) throw new Error('HTTP ' + res.status);
      return res;
    } catch (err) {
      lastErr = err;
      await new Promise(r => setTimeout(r, backoff * (i + 1)));
    }
  }
  throw lastErr;
}
        

네트워크 및 SEO 문제 해결

HTTP 상태코드와 CORS

• 4xx: 클라이언트 요청 오류. 파라미터/인증을 점검합니다.
• 5xx: 서버 내부 오류. 로깅과 알림으로 신속히 대응합니다.
• CORS: 프리플라이트 실패, Access-Control-Allow-Origin 헤더 설정 확인.

HTTP/1.1 204 No Content
Access-Control-Allow-Origin: https://example.com
Access-Control-Allow-Methods: GET, POST, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization
Access-Control-Max-Age: 600
        

SEO 기본 점검

• 고유 제목/설명: 페이지마다 title, meta description을 최적화합니다.
• 링크 가시성: 중요한 내비게이션은 자바스크립트 없이도 접근 가능해야 합니다.
• 크롤러 친화: robots.txt와 sitemap.xml을 제공하고 오류 페이지는 올바른 상태코드를 사용합니다.

접근성 개선(WCAG)

이름/역할/값

• 대화형 컨트롤: button, a 등 기본 요소를 우선 사용합니다.
• ARIA 사용: 역할을 덮어쓰지 말고, 필요한 경우에만 추가 속성을 제공합니다.
• 라이브 영역: 동적 업데이트에는 aria-live를 적용합니다.

색 대비와 텍스트

• 대비 기준: 정상 텍스트는 최소 4.5:1, 큰 텍스트는 3:1을 목표로 합니다.
• 링크 구분: 색상 외에 밑줄 등 시각적 차이를 제공합니다.
• 언어 표기: lang 속성을 정확히 설정해 발음/읽기 품질을 향상합니다.

성능 최적화와 관련 오류

로드 성능

• 리소스 힌트: preload, prefetch를 적절히 사용합니다.
• 이미지 최적화: srcset, sizes, loading="lazy".
• 번들 분할: 초기 로드에 필요한 코드만 제공합니다.

예시: 반응형 이미지

런타임 성능

• 메모리 누수: 타이머/리스너 해제를 습관화합니다.
• 레이아웃 스로틀링: 스크롤/리사이즈에 requestAnimationFrame 또는 debounce.
• 비동기 처리: 대규모 연산은 Web Worker로 오프로드.

보안 점검과 오류 예방

XSS/CSRF

• 출력 인코딩: 사용자 입력을 HTML에 삽입하지 않거나 적절히 이스케이프합니다.
• 콘텐츠 보안 정책(CSP): 인라인 스크립트 제한, 신뢰 도메인만 허용.
• CSRF 방지: 토큰 검증과 SameSite 쿠키 설정.

Content-Security-Policy: default-src 'self'; img-src 'self' https:; script-src 'self'; style-src 'self'; connect-src 'self' https:;
        

에러 노출 최소화

• 사용자 메시지: 내부 스택/쿼리 노출 금지.
• 서버 로깅: 민감정보 마스킹, 접근 제어.
• 서드파티: 외부 SDK 실패에 대비한 격리와 타임아웃.

체크리스트

릴리즈 전 점검

장애 대응 절차

1. 감지: 모니터링 알림 수신, 영향 범위 파악.
2. 완화: 기능 플래그/롤백으로 사용자 영향 최소화.
3. 분석: 로그/추적 기반 원인 규명.
4. 수정: 패치 배포, 재발 방지 테스트 추가.
5. 회고: 문서화 및 프로세스 개선.

부록 및 예시 코드 모음

에러 페이지(404/500) 접근성

<main role="main">
  <section aria-labelledby="error-title">
    <h1 id="error-title">요청하신 페이지를 찾을 수 없습니다 (404)</h1>
    <p>주소를 확인하거나 <a href="/">홈으로 이동</a>하세요.</p>
  </section>
</main>
      

서비스 워커 네트워크 오류 처리

self.addEventListener('fetch', (event) => {
  event.respondWith((async () => {
    try {
      const network = await fetch(event.request);
      return network;
    } catch {
      const cache = await caches.match(event.request);
      return cache || new Response('오프라인입니다.', { status: 503 });
    }
  })());
});
      

로그 필드 표준화

{
  "timestamp": "2025-10-26T21:25:00+09:00",
  "level": "error",
  "message": "API 응답 실패",
  "errorId": "e-20251026-001",
  "context": {
    "route": "/checkout",
    "userAgent": "Mozilla/5.0",
    "locale": "ko-KR"
  }
}