개발자 포트폴리오 로딩 오류를 일주일 고쳐봤더니

• 목록
• 답변
• 글쓰기
• 옵션
  • 수정
  • 삭제

채용 담당자에게 보낸 개발자 포트폴리오가 내 컴퓨터에서는 잘 열리는데, 다른 브라우저에서는 화면이 비거나 버튼이 반응하지 않는다면 문제는 디자인보다 심각합니다. 방문자는 오류 원인을 기다려 주지 않고, 프로젝트가 실제로 작동하지 않는다고 판단하기 때문입니다.

저도 포트폴리오 첫 화면이 간헐적으로 늦게 뜨고 프로젝트 상세 페이지에서 새로고침하면 404가 발생하는 문제를 일주일 동안 추적해봤습니다. 그 과정에서 확인한 핵심은 코드를 무작정 고치기 전에 오류를 재현하고, 네트워크와 실행 환경을 분리해 살펴보는 것이었습니다.

내 컴퓨터에서만 정상인 원인부터 좁혀봤습니다

브라우저와 접속 경로를 바꾸면 단서가 보입니다

가장 흔한 실수는 평소 사용하는 브라우저의 로그인 상태와 캐시에만 의존해 포트폴리오를 확인하는 것입니다. 이미 내려받은 JavaScript 파일과 이미지가 캐시에 남아 있으면 배포 서버에 파일이 없어도 정상처럼 보일 수 있습니다. 시크릿 창, 다른 브라우저, 휴대전화 모바일 데이터로 각각 접속하면 방문자가 실제로 만날 가능성이 높은 상태를 확인할 수 있습니다.

특히 메인 주소로 들어갈 때는 열리지만 /projects/weather-app 같은 하위 경로를 직접 열거나 새로고침할 때 404가 나타난다면 클라이언트 라우팅과 서버 설정을 의심해야 합니다. React나 Vue 기반 단일 페이지 앱은 서버가 해당 경로의 파일을 찾지 못했을 때 기본 문서로 돌려보내는 재작성 규칙이 필요합니다. 반대로 정적 HTML 사이트라면 링크의 대소문자와 실제 디렉터리 이름이 일치하는지 먼저 봐야 합니다.

1. 캐시를 비운 시크릿 창에서 첫 화면과 프로젝트 상세 주소를 각각 직접 엽니다.
2. Chrome뿐 아니라 Safari 또는 Firefox에서 메뉴, 필터, 모달을 눌러봅니다.
3. 와이파이를 끈 휴대전화에서 접속해 느린 네트워크에서도 콘텐츠가 나타나는지 확인합니다.
4. 개발자 도구의 Console에서 빨간 오류를, Network에서 404·403·500 응답을 기록합니다.
5. 오류가 난 URL, 브라우저, 화면 크기, 재현 순서를 한 줄씩 남깁니다.

오류 보고를 “가끔 안 됨”으로 적으면 다시 찾기 어렵습니다. “모바일 Safari에서 프로젝트 상세 주소를 직접 열고 새로고침하면 404 발생”처럼 조건과 행동을 함께 기록하세요.

대소문자와 절대 경로가 배포 후 고장을 만듭니다

macOS나 Windows의 일부 로컬 환경에서는 Profile.png와 profile.png의 차이가 드러나지 않지만, Linux 서버에서는 서로 다른 파일로 처리될 수 있습니다. 로컬에서 보이던 프로필 이미지가 배포 후 깨졌다면 파일명, import 문, Git에 기록된 대소문자를 차례로 맞춰야 합니다. 이름만 바꿨는데 Git이 변경을 인식하지 못한다면 임시 이름으로 한 번 바꾼 뒤 원하는 이름으로 다시 변경하는 방식이 안전합니다.

또한 /assets/app.js처럼 루트 기준 절대 경로를 사용하면 하위 디렉터리에 배포한 포트폴리오에서 파일을 찾지 못할 수 있습니다. 개발 서버 주소와 실제 공개 주소의 경로가 다르지 않은지 확인하고, 빌드 도구의 base 또는 public path 설정을 공개 URL에 맞춰야 합니다. 포트폴리오가 단순 작품 모음인지 평가 자료인지 개념을 다시 잡고 싶다면 Portfolio 용어 설명도 참고할 만합니다. 어떤 형식이든 방문자가 결과물에 도달하지 못하면 구성 의도가 전달되지 않는다는 점은 같습니다.

• 파일 이름과 import 구문의 영문 대소문자를 비교합니다.
• Network 탭에서 깨진 파일의 요청 주소를 복사해 직접 열어봅니다.
• 배포 주소가 도메인 루트인지 하위 경로인지 확인합니다.
• 환경 변수에 로컬 주소나 개발용 API 주소가 남아 있는지 검색합니다.

빈 화면과 느린 첫 로딩을 증상별로 고쳤습니다

JavaScript 오류는 첫 번째 메시지부터 읽습니다

콘솔에 오류가 여러 개 쌓이면 마지막 메시지부터 붙잡기 쉽지만, 실제 원인은 대개 가장 먼저 발생한 예외입니다. 예를 들어 프로젝트 데이터를 가져오는 요청이 실패한 뒤 Cannot read properties of undefined가 이어졌다면 화면 렌더링 코드를 고치기 전에 API 응답 실패부터 해결해야 합니다. 후속 오류는 최초 실패의 결과일 가능성이 높습니다.

비동기 데이터를 받기 전에 배열 메서드를 실행하거나 존재하지 않는 DOM 요소에 이벤트를 연결하는 코드도 빈 화면을 만듭니다. 데이터에는 로딩·성공·빈 결과·실패 상태를 따로 두고, DOM 선택 결과에는 null 검사를 적용하세요. 오류를 숨기기 위해 모든 코드를 거대한 try-catch로 감싸면 화면은 조용해져도 고장 원인을 잃게 됩니다. 사용자가 이해할 수 있는 오류 문구를 보여주되 개발 콘솔에는 요청 주소와 상태 코드를 남기는 편이 낫습니다.

• ReferenceError: 변수명 오타, 스크립트 실행 순서, 모듈 import 경로를 확인합니다.
• TypeError: 값이 null 또는 undefined가 되는 이전 과정을 추적합니다.
• CORS 오류: 프런트 코드의 임시 우회보다 API 서버의 허용 출처 설정을 점검합니다.
• Mixed Content: HTTPS 페이지가 HTTP API나 이미지를 요청하는지 확인합니다.
• Chunk load 실패: 오래된 HTML 캐시가 삭제된 번들 파일을 가리키는지 살펴봅니다.

로딩 속도는 파일 크기와 실행 순서로 나눠봅니다

첫 화면이 늦다고 해서 무조건 서버를 바꿀 필요는 없습니다. Network 탭에서 문서 응답이 늦는지, 큰 이미지 다운로드가 오래 걸리는지, JavaScript 실행 후 화면이 늦게 그려지는지 구분해야 합니다. 문서의 TTFB가 길면 호스팅이나 서버 로직을 확인하고, 수 MB 이미지가 병목이면 WebP·AVIF 변환과 적절한 해상도 조정이 먼저입니다.

포트폴리오 첫 화면에는 이름, 역할, 대표 프로젝트로 이동하는 링크가 빠르게 나타나야 합니다. 화면 밖 갤러리와 동영상은 지연 로딩하고, 필수 CSS와 글꼴 수를 줄이면 체감 속도가 좋아집니다. 다만 성능 점수만 높이려다가 프로젝트 설명을 삭제해서는 안 됩니다. 포트폴리오의 사전적 맥락처럼 결과물은 역량과 과정을 보여주는 묶음이므로, 최적화 대상은 설명 자체가 아니라 전달을 막는 불필요한 자원입니다.

성능 개선 전후에는 같은 기기와 네트워크 조건을 사용하세요. 체감만 비교하지 말고 첫 콘텐츠 표시 시간, 전체 전송량, 가장 큰 요청 파일을 함께 기록하면 개선 효과를 설명하기 쉽습니다.

고친 기록을 신뢰받는 프로젝트 증거로 바꿔봤습니다

장애 기록은 포트폴리오의 약점이 아니라 판단 근거입니다

오류를 모두 없앤 뒤 흔적까지 지우면 방문자는 완성된 화면만 볼 수 있지만, 개발자가 어떤 방식으로 문제를 해결했는지는 알기 어렵습니다. 프로젝트 상세 페이지에 증상, 재현 조건, 원인, 수정, 검증 결과를 짧게 추가하면 디버깅 역량이 드러납니다. “이미지를 최적화했다”보다 “대표 이미지 4장의 총용량을 6.2MB에서 780KB로 줄이고 모바일 첫 표시 지연을 낮췄다”처럼 수치와 조건을 쓰는 편이 설득력 있습니다.

다만 실제 운영 주소, 비밀 키, 사용자 정보, 내부 서버 경로를 장애 기록에 노출하면 안 됩니다. 스크린샷과 로그에서는 토큰과 이메일을 가리고, 공개 저장소의 과거 커밋에도 비밀 값이 남지 않았는지 확인하세요. 포트폴리오가 개인의 작업 결과와 이력을 선별해 보여준다는 의미는 포트폴리오 관련 지식백과에서도 확장해 볼 수 있습니다. 모든 로그를 공개하는 것이 아니라 판단 과정을 이해하는 데 필요한 증거를 선별하는 것이 핵심입니다.

• 증상: 사용자가 실제로 본 화면과 발생 빈도를 적습니다.
• 재현: 기기, 브라우저, URL, 클릭 순서를 네 단계 이내로 씁니다.
• 원인: 추측이 아니라 로그와 네트워크 응답으로 확인한 내용을 적습니다.
• 수정: 바꾼 설정이나 코드와 선택 이유를 설명합니다.
• 검증: 다른 환경에서 재현되지 않았는지와 남은 한계를 밝힙니다.

지금 15분 동안 대표 프로젝트 하나만 깨뜨려 봅니다

당장 할 수 있는 행동은 대표 프로젝트 한 개를 시크릿 창에서 여는 것입니다. 메인 페이지를 거치지 말고 상세 URL을 주소창에 직접 붙여 넣은 뒤 새로고침하세요. 이어서 개발자 도구의 Network에서 상태 코드가 400 이상인 요청을 찾고, Console의 첫 번째 오류 메시지를 복사해 프로젝트 이슈에 남깁니다.

오류가 없다면 네트워크 속도를 느린 모바일 환경으로 제한하고 다시 로드해 보세요. 첫 화면에서 이름과 대표 프로젝트 링크가 나타나기까지 무엇이 기다리게 만드는지 관찰하면 다음 수정 대상이 선명해집니다. 오늘은 모든 페이지를 완벽하게 검사하려 하지 말고 대표 프로젝트 하나의 직접 접속, 새로고침, 느린 연결 세 조건만 통과시키세요. 그리고 이 세 조건의 결과를 README에 날짜와 함께 한 줄로 기록하는 것까지가 실제로 끝낼 수 있는 15분 작업입니다.

1. 시크릿 창에 대표 프로젝트 상세 URL을 직접 입력합니다.
2. 새로고침 후 404와 빈 화면 발생 여부를 확인합니다.
3. Console의 첫 오류와 Network의 실패 요청을 저장합니다.
4. 느린 연결에서 제목과 핵심 링크가 먼저 보이는지 살핍니다.
5. 확인 결과와 다음 수정 한 가지를 README 또는 이슈에 기록합니다.