에러 페이지를 수정할 땐 증상보다 흐름부터 본다

증상이 아니라 흐름을 본다

혼자 웹 개발을 하다 보면, 에러 페이지에서 문제를 만난다. 처음엔 검색한 해결책을 바로 따라 하지만, 반복되는 문제를 겪으며 깨닫게 된다. 뭔가를 바꾸기 전에 먼저 상황을 제대로 파악해야 한다는 것이다.

에러 페이지 문제의 핵심은 한 가지 증상에 집중하는 게 아니라, 사용자가 보는 것과 개발자가 볼 수 있는 신호를 함께 추적하는 것이다. 재현 조건부터 확인하고, 로그와 응답을 살펴본 뒤, 실제 환경에서 어떻게 보이는지 확인해야 한다.

먼저 사용자 영향을 확인한다

문제를 발견했을 때 가장 먼저 할 일은 사용자가 정확히 어떤 상황에서 이 에러를 보는지 파악하는 것이다. 항상 같은 페이지에서 나타나는가, 특정 조건에서만 나타나는가를 정해두면, 나중에 수정했을 때 제대로 고쳐졌는지 판단하기가 훨씬 빠르다.

그 다음은 개발자 관점에서 어떤 신호가 남아 있는지 확인한다:

• 먼저 볼 값: 사용자가 보는 화면과 에러 코드
• 함께 비교할 값: 정상 상태에서는 어떻게 보이는가
• 남겨둘 기록: 콘솔 로그, 응답 코드, 수정한 설정

로컬과 운영의 차이를 의심한다

로컬에서는 정상이었는데 배포 후에 문제가 터진다면, 환경의 차이를 첫 번째 후보로 봐야 한다. 빌드 결과물이 달라질 수 있고, 브라우저 캐시가 개입할 수도 있으며, 설정이 적용되지 않았을 가능성도 있다.

curl -s https://example.com | grep -Ei 'error|exception|status'
npm run build && npm run preview

이 명령으로 실제 배포된 결과물이 어떻게 렌더링되는지 직접 확인할 수 있다.

검증 루틴을 고정해둔다

같은 문제가 또 나오면 더 빠르게 처리하기 위해, 매번 체크하는 순서를 고정하는 게 도움이 된다:

1. 원래 증상이 같은 조건에서 다시 나타나는지 확인한다
2. 로그나 응답에서 바뀐 부분을 명확히 설명할 수 있는지 확인한다
3. 공개 화면, 빌드 결과, 실제 요청 중 적어도 하나로 최종 확인을 한다

마지막으로 기록을 남긴다

문제를 해결한 후, 다음 번 같은 상황이 나올 때를 대비해 짧게라도 기록을 남기면 디버깅 시간이 크게 단축된다. "어떤 증상이 어떤 원인 때문에 나왔는가"를 한 문장으로 정리해두면, 비슷한 문제를 만날 때 빠르게 대응할 수 있다.