“댔다!” 마침내 배포 성공 메시지가 떴을 때 터져 나온 탄성이었다.
(왜냐하면, 처음이라서 슈버페이스까지는 처리가 잘되었는데 버셀? 로 하는 작업이 너무 오래 걸렸다. 그리고 무료 토큰이 끝나서 Railway 다시 옮겨갔는데 버셀과 또 다른 프로세스라서 오류에 오류가 너무 많이 나서 이 날은 집에 10시 넘어서 퇴근…!)
로컬 환경(내 컴퓨터)에서는 완벽하게 돌아가던 시스템이 실제 서버(Railway)에 올리자마자 수십 개의 에러를 뿜어내기 시작했기 때문입니다.
배포 과정에서 마주친 5가지 장애물과 이를 Claude Code와 함께 어떻게 해결했는지, 그리고 성공적인 배포를 위한 체크리스트를 공유해보겠다.
1. 왜 배포 플랫폼으로 ‘Railway’를 선택했나?
서비스의 빠른 배포와 안정적인 운영을 위해 Railway 선택 했다. 로컬에서 작업 할수도 있었지만, 많은 사람들에게 공유를 하려면 웹 배포는 필수였다.
- Git 기반 자동 배포: GitHub에 코드를 올리기만 하면 즉시 서버에 반영됨
- Next.js 최적화: 별도의 복잡한 설정 없이도 Next.js 프로젝트를 자동으로 감지하고 빌드함
- 직관적인 환경 변수 관리: 보안이 중요한 API 키값들을 UI에서 쉽게 관리할 수 있음
2. 장애물 1: “로컬은 되는데 서버는 안 돼!” (타입 에러)
가장 먼저 나를 괴롭힌 것은 TypeScript 타입 에러였다.
로컬에서는 관대하게 넘어가던 코드들이 엄격한 서버 빌드 환경에서는 모두 ‘빨간 줄’ 에러로 변하면서 나의 좌절은 시작했다.
이것까지만, 이것까지만을 저녁 6시부터 시작 되었지만, 좀처럼 빠르게 해결 되지 않아서 울고 싶었다.
ㄱ. 문제 상황
ScopeType이라는 데이터 형식이 여러 파일에서 중복으로 정의되어 있어, 컴파일러가 이를 서로 다른 데이터로 인식하는 문제가 발생했다.
ㄴ. 해결책: “중앙화가 답이다”
Claude Code는 모든 파일에서 공통으로 사용하는 타입을 한 곳(src/types/common.ts)으로 모으라고 제안했다,
이후 모든 화면 코드에서 이 중앙화된 타입을 불러오도록 수정하여 “타입 불일치” 문제를 깔끔하게 해결했다.
3. 장애물 2: 끈질긴 ‘빌드 캐시’의 저주
코드를 수정하고 다시 배포했는데도 서버는 계속 옛날 코드로 빌드되는 기현상이 발생했습니다. 원인은 Railway의 빌드 캐시였다.
ㄱ. 해결 프롬프트 사례
나의 요청: “코드를 수정했는데 서버 반영이 안 돼. 이전 빌드 기록이 남아서 그런 것 같은데, 빌드할 때마다 이전 캐시를 완전히 지우고 새로 빌드하는 명령어를 알려줘.”
ㄴ. 해결책: 빌드 명령어 강제 초기화
Claude Code의 조언에 따라 railway.json 설정 파일에 이전 빌드 내역 삭제(rm -rf .next) 명령어를 추가했다.
그런데, 지금 블로그를 쓰면서 다시 생각해보니 내가 이전의 오류를 보고 너무 지레겁먹어서 AI를 괴롭힌 것이 아닐까 싶기도 했다.
이 한 줄의 코드로 우리는 더 이상 “옛날 코드”와 싸우지 않게 되었다.
4. 장애물 3: “내 데이터가 다 어디 갔지?” (환경 변수)
우여곡절 끝에 사이트가 떴지만, 이번엔 등록했던 사용자 정보와 번역 데이터가 하나도 보이지 않았다.
왜 맨날 산 넘어 산일까? 내가 무엇을 잘못 했길래 되던 것도 안되는 걸까? 하는 마음이 제일 많았다.
그래서, 해결하지 못하면 집에가서도 아른 거릴 것 같아서 저녁 9시가 넘어서까지 집에 갈 수 없었다.
ㄱ. 문제 상황
Supabase 데이터베이스에 접근하기 위한 서비스 역할 키(Service Role Key)가 서버 환경 변수에 등록되지 않았던 것이였다.
버셀에서 세팅 할때는 필요가 없어서, 필요 없는 키인줄 알았는데 내가 사용자 권한처리를 추가 작업하면서 없어서는 안되는 키 값이였던 것이였다.
즉, 이 키가 없으면 보안 정책(RLS) 때문에 데이터를 가져올 권한이 없게 되는 것이였다.
ㄴ. 해결책: 환경 변수 체크리스트 적용
서버 UI에서 다음 키값들을 정확히 입력하고 나서야 데이터가 정상적으로 나타났다.
1.
NEXT_PUBLIC_SUPABASE_URL: 데이터베이스 주소
2.NEXT_PUBLIC_SUPABASE_ANON_KEY: 공개 접속 키
3.SUPABASE_SERVICE_ROLE_KEY: 관리자 전용 비밀 키 (외부 노출 안되는 키 값!)
5. 장애물 4: 사소하지만 치명적인 코드 에러들
실전 배포에서는 아주 작은 오타나 연산자 하나가 빌드 전체를 멈추게 한다는 것도 알게 되었다.
1. 파일 확장자 문제:
import문 끝에.tsx를 붙여서 발생한 에러 수정.
2. 연산자 우선순위:||와??를 괄호 없이 혼용하여 발생한 문법 에러 수정.
> 코드 수정 예시:(A || B) ?? false처럼 괄호를 명확히 써주어야 컴퓨터가 헷갈리지 않는다
6. 마침내 성공: 3일간의 대장정 마무리
우선 돌아가는 것만 하기 위해서 3일 동안 작업한 것을 우선 배포 하였다.
3일만에 뚝딱 하는 것은 진짜 권한도 없고, 동싱성도 없고, 로그도 필요 없이 혼자만 작업 할 수 있는 부분으로 웹 배포까지 뚝딱! 딸깍! 이였다.
그러나, 하면서 욕심이 생겨버렸다. 누구보다도 잘 만들고 싶다는 생각에 해당 제품을 고도화 해나가기로 마음을 먹는 시점이 되었다.
7. 3일동안 작업한 결과물을 웹 배포하면서 배운 교훈
1. 타입 안정성은 ‘생존’의 문제다
: 로컬에서 괜찮다고 넘기지 마세요. 중앙화된 타입 관리는 필수였다.
2. 환경 변수는 배포의 시작과 끝이다
: NEXT_PUBLIC_ 접두사가 붙은 변수는 수정 후 반드시 재빌드를 해야 반영되는 점이였다.
3. AI 파트너의 가치
: Claude Code는 수천 줄의 로그 중에서 단 몇 줄의 핵심 에러를 찾아내고, 해결 방안까지 제시하는 최고의 ‘시니어 개발자’ 역할을 해주었다.
아이디어는 있지만 코딩이 막막했던” 분들에게 해주고 싶은 것은 일단 시작해라! 이다.
기술의 장벽은 확실하게 2025년도보다는 많이 낮춰졌다고 생각한다. 내가 잘 알지 못하는 부분은 AI와 소통하면서 이런 점을 써야하는구나 학습해나가면서 빠르게 산출물을 만들수 있는 방법이라고 생각한다.
어느 한계점에 도달 하면, 분명 유리천장에 막혀 허우적 될때 인내, 끈기, 열정이 있다면 돌파할 수 있는 가장 투명한 유리창이지 않을까? 하는 생각도 든다.
이로써 빠르게 3일만에 배포 하였지만, 전체적인 것은 5일만에 POC는 끝이 날 것 같다.
(그러나, 지금 이 글을 쓰는 와중에도 해당 시스템을 계속 발전 시키고 있어서 매일 일기를 쓰듯 기록을 남길 것 같다)