ISSUE 83 2026년 11월
AI · 비즈니스·경제 · 건강·생활
AI 프로젝트·개발

아이온2 코디 시뮬레이터 데바룩 개발 4주차 – 디버깅 + 배포준비

데바룩 개발기 4주차 — next build가 안 되는데 어떻게 배포하냐고요
데바룩 개발기 4주차 2026.05.01 ~ 05.06 AI코딩 / 바이브코딩

데바룩 개발기 4주차
— next build가 안 되는데 어떻게 배포하냐고요

3주 동안 기능을 쌓고 나서 “이제 세상에 공개하자”라고 했을 때 — 막혀있었습니다.(진짜로) next build가 안 됩니다. TypeScript 에러 4건, 디버그 페이지 가드, CDN 에셋 연결, 면책 고지까지. 개발 환경과 프로덕션 사이의 거리를 좁힌 4주차를 기록했습니다.

데바룩 4주차 — v1.0.0-rc1 배포 가능한 상태

4주차 결과물 — v1.0.0-rc1 Release Candidate

시리즈 1주차 › 2주차 › 3주차 › 4주차 › 5주차

003주가 지나고, 이제 내보내야 했습니다

이 글에서 처음 합류하셔도 따라올 수 있습니다

3주 동안 기능을 미친 듯이 쌓았습니다. 1,677개 아이템, 93종 헤어, 55종 얼굴, 4채널 염색(원하는 색으로 갑옷을 칠하는 기능), 메이크업, 홍채, 속눈썹, 애니메이션, 코디 저장/공유, 피부톤, 랜덤 코디…

이걸 “세상에 공개”하려니까 갑자기 무서워졌습니다. 개발 환경에서 잘 돌아가는 것과 프로덕션(실제 서비스 환경)에서 안정적으로 돌아가는 건 완전히 다른 이야기거든요.

이 글에서 다루는 것: next build 에러 수정, 디버그 페이지 가드, 면책 고지, 로딩 UI, Static Export, CDN URL 전환, v1.0.0-rc1 태그까지. “배포 준비”가 기능 개발만큼 손이 많이 간다는 걸 처음으로 실감한 주차를 기록한 과정입니다.


01일단 빌드부터 성공시켜야 합니다

Step A — TypeScript 에러 4건과의 씨름

next build(Next.js 프레임워크의 최종 빌드 명령어)를 처음 돌렸더니 TypeScript(코드 오류를 미리 잡아주는 언어) 에러 4건이 터졌습니다. 개발할 때는 매번 전체 빌드를 하지 않고 빠른 확인만 했는데, 최종 빌드에서 평소에 안 잡히던 것들이 한꺼번에 나온 것이죠.

  • ERR 01
    FaceDebugViewer — existingCompile 타입
    → 디버그 페이지 관련. 개발 중에만 쓰던 코드라 타입 정의가 느슨했음. 명시적 타입 선언으로 수정.
  • ERR 02
    FaceDebugViewer — skinning 관련 타입
    → 3D 스키닝(뼈대 움직임) 데이터 구조 타입이 실제 Three.js API와 불일치. 올바른 타입으로 교체.
  • ERR 03
    HairDebugViewer — derivatives 관련
    → GLSL 셰이더 코드에서 쓰는 함수(fwidth)가 TypeScript 타입 정의에 없었음. 타입 선언 추가.
  • ERR 04
    HairDebugViewer — controlsRef 타입
    → 카메라 조작 컨트롤의 ref(참조값) 타입이 null을 허용하지 않게 되어있었음. nullable 타입으로 수정.

전부 디버그 페이지(개발 중에만 쓰는 테스트 화면) 관련이었습니다. 기능 페이지에서는 에러가 없었던 것이죠. 그래도 빌드는 전체가 통과해야 하니까 하나씩 고쳤습니다.

next build 성공. 에러 4건 수정 후 빌드가 통과됐습니다.(진짜 안도했습니다) 이 순간이 4주차에서 가장 안도했던 순간이었는데요 — 동시에 “아, 배포 준비가 이제 시작이구나”라는 걸 깨달았습니다.

디버그 페이지를 프로덕션에서 숨기기

개발 중에 만든 디버그 페이지가 5개 있었습니다. /debug/face, /debug/hair 등 — 내부 테스트용으로 만든 화면들인데요. 이걸 실제 서비스에서 그냥 열어두면 곤란합니다.

DevOnly 레이아웃 가드를 만들었습니다. NODE_ENV === 'production'(현재 환경이 프로덕션인지 확인하는 값)이면 디버그 페이지를 404(없는 페이지) 오류로 리다이렉트하는 방식입니다. 내부 API 중 썸네일 저장 기능(/api/save-thumbnail)도 프로덕션에서는 비활성화했습니다.


02놓치기 쉬운 것들 — 면책 고지, robots.txt, 로딩 UX

클로드(Claude)가 “배포 전 체크리스트”를 짚어준 덕분에 챙긴 것들

“배포 전에 뭐 체크해야 해?”라고 그와중 클로드(Claude)에게 물었습니다. 나온 목록이 꽤 많았습니다. 그 중에서 제가 혼자였으면 나중에야 생각났을 것들을 중심으로 정리합니다.

면책 고지 페이지

이 프로젝트는 팬 프로젝트입니다. 게임 원본 파일을 분석해서 만든 거니까 — 법적으로 안전하게 서비스하려면 면책 고지가 명확하게 있어야 했습니다.

“본 사이트는 비공식 팬 프로젝트입니다. NCSOFT, 아이온2의 공식적인 승인·보증·후원을 받지 않았습니다. 저작권자의 요청이 있을 경우, 관련 콘텐츠를 즉시 삭제하겠습니다.”

별도 면책 고지 페이지를 만들고, 모든 페이지 하단에도 표시했습니다. 처음부터 명확히 해두는 게 맞다고 판단했습니다.

robots.txt

검색 엔진 크롤러(구글 등이 웹사이트를 자동으로 읽어가는 프로그램)가 디버그 페이지를 수집하지 않도록 robots.txt(크롤러에게 접근 허용/차단을 알려주는 파일)를 추가했습니다. 디버그 경로는 전부 Disallow로 처리했습니다.

로딩 프로그레스 바

에셋(3D 모델, 텍스처 등 그래픽 파일들) 전체 용량이 17GB에 달합니다. 첫 로딩 시 시간이 꽤 걸리는데, 화면이 그냥 흰색이면 사용자는 “오류가 났나?” 하고 당황합니다.

useProgress(R3F drei 라이브러리의 로딩 진행률 훅 — drei는 Three.js를 더 쉽게 쓰기 위한 도구 모음)로 GLTF(3D 모델 파일 형식)와 텍스처 로딩 진행률을 실시간으로 받아서 LoadingOverlay를 만들었습니다. 로고 + 프로그레스 바 + 퍼센트 표시. 로딩 화면이 생기니까 훨씬 서비스답게 느껴졌습니다.

데바룩 로딩 화면 — 로고 + 프로그레스 바 + 퍼센트

로딩 프로그레스 바 구현 — 17GB 에셋 로딩 중 사용자 경험 개선


03Cloudflare에 올리기 위한 Static Export

Step B — CDN URL 전환과 17GB 에셋 분리

데바룩을 올릴 플랫폼으로 Cloudflare Pages(정적 웹사이트를 무료로 빠르게 배포할 수 있는 서비스)를 선택했습니다. Cloudflare Pages에서 Next.js 앱을 올리려면 Static Export(사전에 모든 페이지를 HTML 파일로 변환해두는 방식)가 필요했습니다.

next.config.ts(Next.js 설정 파일)에 output: 'export' 한 줄을 추가했습니다. 그런데 문제가 하나 있었습니다 — 17GB짜리 에셋을 어떻게 처리하느냐는 것이죠.

17GB 에셋을 CDN으로 분리

3D 모델과 텍스처 파일 17GB를 웹사이트 코드와 같이 올릴 수는 없습니다. Cloudflare R2(클라우드 파일 저장 서비스 — S3와 비슷한 개념)에 에셋을 올리고, 코드에서는 CDN URL(콘텐츠를 빠르게 배포하는 서버의 주소)로 접근하도록 전환했습니다.

TypeScript — CDN URL 헬퍼 함수
// 이 코드가 하는 일: 에셋 경로를 CDN 주소로 자동 변환한다

const CDN_BASE =
  process.env.NEXT_PUBLIC_ASSET_CDN_URL ||
  “https://pub-fe4394f6289f428e9533ffd95b0ccf86.r2.dev”;

export function getModelUrl(path: string): string {
  return `${CDN_BASE}${path}`;
}

이 함수를 하나 만들어두고, 3D 모델·텍스처·애니메이션을 로드하는 코드 전체에 적용했습니다. CharacterModel, texture-loader, animation, eyelash… 에셋을 읽는 곳마다 전부 이 헬퍼를 거치도록 했습니다.

환경 변수(NEXT_PUBLIC_ASSET_CDN_URL)로 CDN 주소를 설정하니까, 나중에 CDN 주소가 바뀌어도 코드를 건드릴 필요가 없습니다. 개발 환경에서는 로컬 서버를, 프로덕션에서는 실제 CDN을 자동으로 쓰는 구조입니다.


04v1.0.0-rc1 — “배포해도 되는 상태”

4주만의 Release Candidate

BASH — v1.0.0-rc1 태그
git tag -a v1.0.0-rc1 -m “Release Candidate 1”

이 한 줄을 치는 게 4주차에서 가장 뭉클한 순간이었습니다.(4주 만에 여기까지 왔습니다) Release Candidate(RC — 정식 출시 전 최종 후보 버전)라는 이름을 붙인다는 건 “이제 여기에 더 이상 새 기능을 넣지 않겠다. 이 상태로 세상에 내보낸다”는 선언인 것이죠.

4주차에서 Claude가 가장 도움이 됐던 순간

이 주의 가장 큰 클로드(Claude) 활용 포인트는 “놓치기 쉬운 것들을 챙겨준 것”이었습니다. “배포 전에 뭐 체크해야 해?”라고 물었더니 항목을 체계적으로 짚어줬습니다.

  • TypeScript 빌드 에러 체크
  • 디버그 페이지 프로덕션 가드
  • 내부 API 라우트 프로덕션 비활성화
  • 면책 고지 페이지
  • robots.txt 크롤러 제어
  • 로딩 UX (프로그레스 바)
  • OG 메타 태그 (소셜 미디어 공유 시 미리보기)

혼자 했으면 면책 고지 같은 건 사이트를 공개하고 나서야 “아, 이거 넣었어야 했는데”라고 생각했을 것입니다. AI에게 체크리스트를 요청하는 것 자체가 중요한 활용 방법이라는 걸 이번에 확실히 느꼈습니다.

INSIGHT — 4주의 회고

1주차에 “게임 파일에서 3D 모델 뽑을 수 있나?” 확인하던 게 엊그제 같은데, 4주차에 v1.0.0-rc1 태그를 달고 있습니다. 코드의 대부분은 클로드(Claude)가 짰고, 저는 방향을 잡고 문제를 진단하고 게임 파일 구조를 이해하는 역할이었습니다.(이게 바이브코딩의 분업입니다) 바이브코딩이 대충 코드를 생성하는 게 아니라, AI와 함께 시스템을 설계하고 디버깅하는 과정이라는 걸 이 프로젝트에서 확실히 느꼈습니다. 클로드(Claude)가 아무리 좋은 코드를 짜줘도 “왜 갑옷이 회색이지?”는 내가 텍스처를 열어봐야 알 수 있고, “왜 얼굴이 녹아내리지?”는 내가 GLTF 바이너리를 파싱해봐야 알 수 있습니다.

4주차 결과

  • next build 성공 — TypeScript 에러 4건 수정
  • 디버그 5페이지 프로덕션 가드 완료
  • 면책 고지 페이지 + robots.txt 추가
  • 로딩 프로그레스 바 구현
  • Static Export 설정 완료
  • CDN URL 전체 적용 (모든 에셋 경로)
  • v1.0.0-rc1 태그 — Release Candidate
  • 배포 가이드 문서 완성 (Cloudflare Pages + R2 전 과정)

NEXT — 5주차 예고

드디어 세상에 공개합니다 — 근데 버그가 있습니다

Cloudflare Pages + R2 17.4GB 업로드, daevalook.kr 도메인 연결, CDN 텍스처 룩업 키가 전부 날아가는 버그가 터집니다…도메인 연결부터 OG 이미지, 5주 회고까지 기록했습니다.

이 시리즈: 1주차 · 2주차 · 3주차
바이브코딩에 대해 더 알고 싶다면: AI 코딩 완전 가이드 — 바이브코딩이 실제로 어떻게 작동하는가

더 많은 인사이트가 필요하신가요?

AI와 비즈니스·경제 중심의 다른 콘텐츠도 확인해보세요.

전체 콘텐츠 보기

ESC로 닫기