"웹 개발부터 배포, 운영까지 (6/8) — 빌드, 컴파일, 번들 그리고 Turbopack: 프론트엔드가 배포 가능한 파일이 되기까지"

-

개발자가 읽기 좋은 코드와 브라우저가 실행하기 좋은 코드는 대체로 같은 형태가 아니다.

핵심 요약

  • 프론트엔드 빌드는 개발용 소스 코드를 브라우저와 서버가 실행 가능한 산출물로 바꾸는 과정이다.
  • 컴파일, 트랜스파일, 번들링, 코드 분할은 서로 다른 단계지만 초보자에게는 한 덩어리처럼 보이기 쉽다.
  • Next.js 문서 기준으로 Turbopack은 기본 번들러이며, 개발 속도와 증분 처리 경험을 개선하는 방향에 초점이 있다.
  • 배포 문제의 상당수는 앱 코드보다 빌드 산출물, 환경 변수 주입, 정적 자산 경로, 런타임 차이에서 발생한다.

1. 빌드는 정확히 무엇을 의미할까

빌드는 "코드를 실행 파일이나 서비스 산출물로 만드는 전체 과정"이라고 보는 편이 가장 실용적이다.

프론트엔드에서는 보통 아래 작업이 함께 묶인다.

  • 최신 문법이나 JSX를 브라우저가 이해할 수 있는 형태로 바꾸기
  • 여러 파일 의존성을 정리하기
  • 필요한 코드만 묶고 불필요한 코드는 줄이기
  • 정적 자산 경로를 정리하기
  • 프로덕션용 최적화를 적용하기

그래서 npm run build 한 줄은 짧지만, 실제로는 애플리케이션 구조를 배포 가능한 상태로 재구성하는 과정이다.

2. 컴파일, 트랜스파일, 번들은 어떻게 다를까

입문자가 가장 헷갈리는 구간이라 구분을 한 번 잡아 두는 것이 좋다.

컴파일

넓은 의미로는 소스 코드를 다른 실행 가능한 형태로 바꾸는 전체 변환을 가리킨다. 프론트엔드 문맥에서는 엄밀한 전통적 컴파일보다 더 넓게 쓰인다.

트랜스파일

자바스크립트 생태계에서는 "비슷한 수준의 언어를 다른 형태로 변환"하는 경우가 많다. 예를 들어 TypeScript를 JavaScript로, JSX를 일반 함수 호출 형태로 바꾸는 작업이 여기에 가깝다.

번들링

여러 파일과 의존성을 실행 단위로 묶는 작업이다. 브라우저가 필요한 파일을 효율적으로 받도록 묶음과 분할 전략을 만든다.

코드 분할

처음부터 모든 코드를 한 번에 보내지 않고, 라우트나 기능 단위로 나눠 필요한 시점에만 내려보내는 방식이다. 초기 로딩 성능과 캐싱 전략에 직접 연결된다.

이 네 가지는 서로 경쟁 개념이 아니라 빌드 파이프라인 안의 역할 분담이다.

3. 왜 개발 중에는 빠른데 배포 빌드에서는 느리거나 깨질까

개발 서버와 프로덕션 빌드는 목표가 다르다.

개발 서버는 빠른 피드백이 중요하다. 저장 후 즉시 반영되고, 에러 위치가 잘 보이며, 일부 최적화는 생략해도 된다.

반면 프로덕션 빌드는 결과물 안정성이 중요하다. 정적 파일 생성, 서버 번들 정리, 최적화, 환경 변수 반영, 이미지 처리, 코드 분할 검증 같은 작업이 본격적으로 들어간다.

그래서 개발 모드에서 잘 돌아가던 앱이 배포 직전 빌드에서 실패하는 일은 흔하다. 대표적으로는 다음과 같다.

  • 브라우저 전용 API를 서버 렌더링 구간에서 사용함
  • 개발 환경에만 있던 환경 변수가 운영 빌드에 없음
  • import 경로 대소문자 차이가 로컬에서는 통과하지만 운영 리눅스에서는 실패함
  • 동적 라우팅이나 정적 자산 경로가 배포 환경 기준으로 맞지 않음

4. Turbopack은 어디에 들어오는가

Turbopack은 Next.js 생태계에서 빌드와 번들링 경험을 담당하는 도구다. Next.js 공식 문서에서는 Turbopack이 기본 번들러라고 설명하고, Webpack이 필요하면 --webpack 플래그로 전환하도록 안내한다.

중요한 포인트는 "Turbopack이 마법처럼 앱을 빠르게 만든다"가 아니다. 더 정확한 이해는 이렇다.

  • 변경된 부분만 빠르게 다시 계산하려 한다
  • 개발 중 반복 피드백 시간을 줄이는 데 강점이 있다
  • 프로젝트가 커질수록 빌드 도구 선택이 개발 경험에 직접 영향을 준다

즉, Turbopack은 앱의 비즈니스 로직을 바꾸는 도구가 아니라, 개발 코드가 실행 산출물로 바뀌는 경로를 더 효율적으로 관리하는 레이어다.

5. 배포 관점에서 빌드 시스템을 어떻게 바라봐야 할까

빌드 도구를 프론트엔드 내부 기술로만 보면 운영 문제가 잘 안 보인다. 실제로는 빌드 결과가 곧 배포 단위가 된다.

정적 파일 배포

HTML, CSS, JS가 정적으로 생성되면 CDN이나 정적 호스팅으로 보낼 수 있다.

서버 실행 배포

서버 렌더링이나 API 라우트가 있으면 단순 파일 업로드만으로 끝나지 않는다. 런타임과 프로세스가 필요하다.

환경 변수 주입

빌드 시점에 결정되는 값과 런타임 시점에 읽는 값을 구분하지 않으면 "운영에서만 값이 안 바뀌는" 문제가 생긴다.

캐시와 산출물 일관성

이전 빌드 캐시가 남아 있거나 배포 노드마다 산출물이 다르면 재현이 어려워진다. 빌드 재현성은 운영 안정성과 직결된다.

6. 입문자가 먼저 익혀야 할 실전 질문

도구 이름보다 아래 질문이 더 중요하다.

  1. 이 앱은 정적 산출물만 있으면 되는가, 서버 런타임이 필요한가
  2. 이 값은 빌드 타임에 고정되는가, 실행 중에 바뀌는가
  3. 에러는 개발 서버에서만 보이는가, 실제 프로덕션 빌드에서도 재현되는가
  4. 초기 로딩 속도와 이후 페이지 이동 속도에 어떤 코드 분할이 영향을 주는가

이 질문에 답할 수 있으면 Webpack이든 Turbopack이든 도구 이름에 덜 끌려간다. 결국 중요한 것은 "내 코드가 어떤 산출물로 변하고, 그 산출물이 어디서 어떻게 실행되는가"를 이해하는 일이다.

참고 자료

  • Next.js Docs, Getting Started: Installation — https://nextjs.org/docs/pages/getting-started/installation
  • Next.js Docs, API Reference: Turbopack — https://nextjs.org/docs/pages/api-reference/turbopack
  • Next.js Docs, Deploying — https://nextjs.org/docs/pages/building-your-application/deploying

이 글은 웹 개발부터 배포, 운영까지 시리즈의 6/8편이다.

댓글

댓글 쓰기

이 블로그의 인기 게시물

"LLM 핵심 학습 (1/6) — 기본: 토큰화·임베딩·어텐션·위치 인코딩"

-
이미지
(시리즈 시작) 📚 시리즈 목차 2/6 파인튜닝 → 트랜스포머 한 블록의 데이터 흐름을 문자열 → 토큰 → 임베딩 → 어텐션 → 출력 표현 까지 손으로 풀어 본다. 이번 편이 끝나면 "왜 \(\sqrt{d_k}\)로 나누는가", "RoPE는 무엇을 회전시키는가", "한국어가 영어보다 토큰이 많은 까닭은 무엇인가"가 한 줄로 설명될 수 있다. 0. 학습 목표 이 편을 마치면 다음을 직접 할 수 있다. BPE 토크나이저 가 어휘를 어떻게 학습하고 새 문자열을 어떻게 자르는지 종이 위에서 시뮬레이션한다. 임베딩 행렬 의 모양과 초기화, weight tying의 의미를 한 줄로 설명한다. Scaled Dot-Product Attention 의 식을 차원 단위로 추적하고 PyTorch 30줄로 재현한다. Multi-Head Attention 이 한 헤드와 비교해 무엇이 다른지, 헤드 수가 늘면 어디가 비싸지는지 답한다. Sinusoidal·RoPE·ALiBi 세 위치 인코딩의 식과 외삽 성질을 구분한다. 컨텍스트 확장이 왜 \(O(N^2)\)인지, "Lost in the Middle"이 왜 발생하는지 설명한다. 1. 핵심 요약 트랜스포머의 입력은 문자열 이 아니라 정수 ID 시퀀스 다. 토크나이저가 문자열 → ID로 자른다. 임베딩은 정수 ID를 \(d\)차원 벡터로 lookup하는 학습 가능한 테이블이다. Self-Attention은 \(\text{softmax}(QK^\top / \sqrt{d_k}) V\) 한 줄이 핵심이고, 멀티헤드는 같은 연산을 여러 부분 공간에서 병렬화한 것이다. 위치 정보는 임베딩에 직접 더하거나(Sinusoidal), Q·K에 회전을 가하거나(RoPE), 어텐션 스코어에 거리 패널티를 더해서(ALiBi) 주입한다. 컨텍스트 길이 \(N\)에 대해 표준 어텐션은 \(O(N^2)\) 비용을 갖고, 긴 컨텍스트에서는 중간 위...
Read more »

"LLM 핵심 학습 (2/6) — 파인튜닝: LoRA·QLoRA·증류·Adapter"

-
이미지
← 1/6 기본 📚 시리즈 목차 3/6 디코딩과 생성 → 사전학습된 LLM을 내 데이터 에 적응시키는 방법을 비용·메모리·일반화 관점에서 정리한다. Full FT의 한계 → Adapter → LoRA → QLoRA → Distillation 순으로 같은 그림을 점점 확대해 본다. 0. 학습 목표 Full fine-tuning의 메모리 병목을 옵티마이저 상태·그래디언트·가중치·활성화 의 4분할로 설명한다. Adapter(Houlsby 2019)와 LoRA(Hu 2021)의 식 차이를 한 줄로 적는다. LoRA의 \(A, B\) 행렬이 왜 저랭크 이고, rank \(r\) 선택이 무엇을 결정하는지 답한다. QLoRA(Dettmers 2023)의 NF4·double-quant·paged optimizer를 분리해서 설명한다. Catastrophic Forgetting을 분포 시프트 관점에서 정의하고 완화 기법을 두 개 이상 든다. Hinton 2015의 Knowledge Distillation 식을 손으로 유도한다. 1. 핵심 요약 Full FT는 메모리/디스크/시간 모두 비싸다. 7B 모델 full FT는 V100 8장 + A100 1장으로도 큰 부담이다. PEFT(파라미터 효율 파인튜닝) 일가족은 극히 일부 파라미터만 학습 해 같은 효과를 얻는다. LoRA: \(\Delta W = BA\) (rank \(r \ll \min(d_{\text{in}}, d_{\text{out}})\))로 가중치 업데이트를 저랭크 분해. QLoRA: 베이스 모델을 4-bit(NF4)로 양자화한 채 LoRA만 풀-정밀(BF16)으로 학습. Catastrophic Forgetting: 새 분포에 적응하느라 이전 능력이 무너지는 현상. PEFT 자체가 부분 완화책. Distillation: 큰 교사 모델의 soft target 을 학습 신호로 써서 작은 학생 모델 을 만든다. 2. 직관: 왜 사전학습만으로는 부족한가 사전학습은 일반...
Read more »

"ML 기초 학습 (1/9) — 머신러닝과 sklearn: 학습의 좌표계"

-
이미지
(시리즈 시작) 📚 시리즈 목차 2/9 이웃 알고리즘 → 이 시리즈는 신경망과 로컬 LLM으로 가기 전에 손에 익혀 둬야 할 머신러닝 기초 9편이다. 1편은 모든 ML 코드가 공유하는 공통 문법 을 잡는 데 쓴다. sklearn은 그 문법을 가장 일관되게 보여주는 도구다. 이번 편이 끝나면 어떤 모델을 만나도 fit → predict → score → 평가 흐름이 같다는 것이 손에 잡힌다. 0. 학습 목표 이 편을 마치면 다음을 할 수 있어야 한다. 지도학습·비지도학습·강화학습을 한 문장씩 구분해 설명한다. sklearn의 estimator 인터페이스 ( fit , predict , score , transform )를 코드 한 화면 안에서 쓸 수 있다. train/validation/test 분할을 왜 하는지, 어디서 데이터 누수가 생기는지 식과 그림으로 설명한다. 분류·회귀의 핵심 평가 지표(accuracy, precision, recall, F1, MSE, R²)를 정의에서 직접 계산할 수 있다. k-fold 교차검증 을 코드 한 줄로 돌리고, 결과의 평균과 표준편차를 함께 보고할 수 있다. Pipeline 으로 전처리와 모델을 묶어 데이터 누수를 구조적으로 막는 방법을 설명한다. 1. 핵심 요약 머신러닝은 데이터에서 함수 \(f: X \to Y\)를 찾는 작업 이다. 어떤 모델이든 이 본질은 같다. sklearn은 모든 모델을 같은 인터페이스( fit , predict , score )로 통일해, 모델을 바꿀 때 한 줄만 바꾸면 되게 한다. train/val/test 세 분할이 표준이다. 검증으로 하이퍼파라미터를 고르고, 테스트는 마지막에 한 번만 본다. 데이터 누수 (test 정보가 train에 새는 현상)는 ML 입문자가 가장 자주 만드는 실수이며, Pipeline + cross_val_score 조합으로 구조적으로 막을 수 있다. 평가 지표는 문제 유형 (분류/회귀) 과 클래스 불균형...
Read more »