API 파일 업로드 기능이 안 될 때 처음 볼 로그

파일 업로드가 안 된다고 하면, 처음부터 정답을 찾으려고 하면 오히려 더 오래 걸린다. 정상과 비정상의 차이부터 찾는 게 중요하다.

공개 URL에서 메타 태그 확인

API 엔드포인트가 제대로 공개되어 있는지 먼저 확인한다.

curl -s https://example.com/api/upload | head -20
curl -I https://example.com/api/upload

HTTP 상태 코드가 200인지, 아니면 404나 403 같은 오류인지 확인한다. 만약 405 Method Not Allowed가 나면 POST 메서드를 지원하지 않는다는 뜻이다.

로컬과 배포 환경 비교

로컬에서는 파일 업로드가 잘 되는데 운영 서버에서만 문제가 난다면, 환경 차이를 확인해야 한다.

npm run build
npm run start

로컬 빌드와 배포 빌드 환경에서 파일 업로드를 테스트해 본다. 특히 다음 부분을 확인한다:

• 환경변수 (파일 저장 경로, URL 베이스)
• 빌드 시간의 차이
• 사용하는 라이브러리 버전

응답 로그 확인

브라우저 개발자 도구의 Network 탭에서 업로드 요청의 응답을 본다. 에러 메시지가 있으면 그 내용으로 빠르게 판단할 수 있다.

curl -F "[email protected]" https://example.com/api/upload

커맨드 라인에서 직접 multipart 요청을 보내 본다. 응답 상태 코드와 바디 내용을 확인하면 서버 측 문제인지 클라이언트 측 문제인지 알 수 있다.

빌드 로그와 메타데이터

빌드 로그에서 경고나 에러가 있었는지 확인한다. API 라우트 파일이 제대로 번들링되었는지 확인하려면:

# .next/server 디렉토리에서 업로드 API 파일 확인
ls -la .next/server/app/api/upload/

단계별 수정

1. 원래 상황을 정확히 기록한다 (에러 메시지, 상태 코드)
2. 한 가지만 수정한다 (예: 파일 크기 제한 제거)
3. 로컬과 배포 환경 모두에서 테스트한다
4. 수정이 효과가 있었는지 명확히 한다
5. 모든 게 정상이면 추가 확인은 멈춘다

파일 업로드는 브라우저, 네트워크, 서버가 모두 함께 동작해야 하므로 각 단계를 따로 테스트하는 게 중요하다.