Vercel Next.js 첫 배포: 환경변수와 Production URL 연결

TaskFlow는 작업을 관리하는 예제 앱입니다. 이 선택 실습에서는 앱을 배포하고 서버·설정·운영 결과를 확인합니다.

이번 주제: Vercel Next.js 첫 배포: 환경변수와 Production URL 연결.

선택: 연재 프로젝트와 전체 자료

연재 프로젝트를 이어 만드는 분을 위한 자료입니다. 이 글의 개념과 예제만 찾으셨다면 필요한 파일과 실행 방법만 펼쳐보세요.

TaskFlow 프로젝트 적용

이 글부터 시작하는 전체 프로젝트

시작 ZIP — deploy-step-02-artifact-strategy-full-20260928을 새 폴더에 풀고, 이번 단계 완료 ZIP은 다른 폴더에 풀어 비교합니다. ZIP 안 프로젝트 폴더의 package.json 위치가 실행 루트입니다.

출발점은 Next.js 누적 TaskFlow와 같은 38단계 소스입니다. 프로젝트에는 홈·로그인·개인 작업 화면, 작업 추가·완료·삭제, Route Handler와 캐시 예제가 들어 있습니다. 설치 버전을 고정한 package-lock.json도 포함합니다.

이번 변경 이유: Vercel에서 실제 사용하는 환경변수 이름과 배포 결과 기록란을 준비합니다.

• docs/deployment-plan.md
• docs/server-access-runbook.md

1. 시작 ZIP을 풀고 npm ci로 의존성을 설치합니다. Node.js 24와 npm을 사용합니다.
2. 위 변경 파일을 아래 전체 내용 또는 완료 ZIP의 같은 경로와 대조해 적용합니다. 다른 앱 파일은 유지합니다.
3. npm run typecheck, npm run build를 실행합니다. 오류가 있으면 첫 오류의 파일·명령을 기록하고 해결한 뒤 진행합니다.
4. npm run setup-auth로 일회용 로컬 학습 계정을 설정한 후 npm run dev를 실행합니다. 생성된 .env.local과 입력 값은 공유하지 않습니다.

예상 결과: 홈과 로그인 화면은 공개됩니다. 로그인 전 /tasks는 로그인 화면으로 이동하고 /api/tasks는 401을 반환합니다. 로그인 후 작업 목록에서 추가·완료·삭제를 확인합니다. /cache-lab의 별도 캐시 실습은 npm run cache-api가 필요합니다.

3단계 SSH는 선택 학습입니다. 필수 시작본은 2단계이며, 완료 ZIP에 있는 서버 runbook은 참고 문서입니다. 앱 파일은 동일합니다.

저장·운영 범위: 작업은 단일 Node 프로세스 메모리에 저장되고 인증은 학습용 계정 예제입니다. 서버 재시작·서버리스 인스턴스 사이의 데이터 유지는 보장하지 않습니다. 로컬 실행 확인과 실제 운영 서비스 구축은 구분하며, 원격 배포·DNS·SSH·CI·롤백 결과는 직접 실행한 항목만 문서에 기록합니다.

# TaskFlow Deployment Plan


## Build
- package manager: npm
- install: npm ci
- build: npm run build


## Primary deployment
- platform: Vercel
- environment: Production


## Alternative deployment
- Firebase Hosting: static output일 때 검토
- Firebase App Hosting: server runtime이 필요할 때 검토


## Verification
- Production URL 응답
- 주요 화면 확인
- 환경변수 확인
- 주요 route 확인
- 현재 commit 확인
- rollback 가능 여부 확인

## Runtime decision


- static-only: no
- server runtime required: yes
- reasons:
  - Route Handler
  - server-side environment variables


## Primary
Vercel Production


## Firebase alternative
App Hosting 우선 검토


## Static variant
정적 결과물로 분리할 경우 Firebase Hosting 검토

## Production deployment


- deployment URL: 운영 문서에서 관리
- commit SHA: 배포마다 기록
- deployment status: 확인
- build log: 확인
- smoke test: 확인

# Server Access Runbook


## Connection
- host: 저장하지 않음
- user: 환경별 문서에서 별도 관리
- authentication: SSH key 우선
- private key: 저장소에 포함 금지


## Before upload
1. 대상 서버 확인
2. 현재 경로 확인
3. 배포 대상 경로 확인
4. 기존 파일 상태 확인


## After upload
1. 파일 존재 확인
2. owner / permission 확인
3. 서비스가 실제 경로를 읽는지 확인
4. HTTP 결과 확인


## Never commit
- private key
- password
- access token
- production secret

# 기존 앱에서 실제 사용하는 변수만 설정하세요. 값은 개발/운영 플랫폼에서 별도 관리합니다.
NEXT_PUBLIC_API_URL=
API_SECRET=

# TaskFlow Deployment Plan


## Build
- package manager: npm
- install: npm ci
- build: npm run build


## Primary deployment
- platform: Vercel
- environment: Production


## Alternative deployment
- Firebase Hosting: static output일 때 검토
- Firebase App Hosting: server runtime이 필요할 때 검토


## Verification
- Production URL 응답
- 주요 화면 확인
- 환경변수 확인
- 주요 route 확인
- 현재 commit 확인
- rollback 가능 여부 확인

## Runtime decision


- static-only: no
- server runtime required: yes
- reasons:
  - Route Handler
  - server-side environment variables


## Primary
Vercel Production


## Firebase alternative
App Hosting 우선 검토


## Static variant
정적 결과물로 분리할 경우 Firebase Hosting 검토

## Production deployment


- deployment URL: 운영 문서에서 관리
- commit SHA: 배포마다 기록
- deployment status: 확인
- build log: 확인
- smoke test: 확인

# Server Access Runbook


## Connection
- host: 저장하지 않음
- user: 환경별 문서에서 별도 관리
- authentication: SSH key 우선
- private key: 저장소에 포함 금지


## Before upload
1. 대상 서버 확인
2. 현재 경로 확인
3. 배포 대상 경로 확인
4. 기존 파일 상태 확인


## After upload
1. 파일 존재 확인
2. owner / permission 확인
3. 서비스가 실제 경로를 읽는지 확인
4. HTTP 결과 확인


## Never commit
- private key
- password
- access token
- production secret

# 배포·서버 04 — deploy-step-04-vercel-production

이 ZIP은 배포 준비·운영 문서와 해당 회차 설정/코드 조각을 누적한 적용 자료입니다. 실행 앱 전체는 포함하지 않습니다. 기존 deploy-step-00-build-ready 프로젝트에 해당 파일을 검토하여 적용하세요. 이 ZIP 루트에서 npm ci/build를 실행하는 구조가 아닙니다.

.env.example은 값이 빈 설정 안내입니다. 독자의 앱에서 사용하는 변수만 .env.local 또는 플랫폼의 해당 환경에 설정하세요. URL·계정·비밀키를 ZIP에 넣지 않습니다.

이 자료에는 실제 배포·DNS 변경·SSH 접속·메일/알림·롤백 결과가 없습니다. 운영 작업은 독자가 본인 환경과 권한을 확인한 후 수행해야 합니다. 문서의 확인 항목은 수행할 체크리스트이며 이미 통과했다는 기록이 아닙니다.

이전 체크포인트

deploy-step-02-artifact-strategy

배포 전 확인

npm ci
npm run build

두 명령이 성공한 상태에서 Vercel 프로젝트를 연결합니다.

TaskFlow 환경변수 예시

프로젝트에 실제로 필요한 변수만 등록합니다.

NEXT_PUBLIC_SITE_URL=https://your-production-domain.example
API_SECRET=production-secret

위 값은 구조 예시입니다. 실제 Secret은 본문, 저장소, ZIP에 포함하지 않습니다.

deployment 기록

docs/deployment-plan.md에 실제 값을 안전하게 기록할 수 있는 필드를 추가합니다.

## Production deployment

- deployment URL: 운영 문서에서 관리
- commit SHA: 배포마다 기록
- deployment status: 확인
- build log: 확인
- smoke test: 확인

공개 블로그 예제에는 개인 프로젝트의 실제 비공개 URL이나 Secret을 그대로 넣지 않습니다.

실행·결과 확인

이 문서는 배포 방법을 설명하는 본문입니다. 실제 Vercel 계정에서의 deployment 성공 여부는 독자의 프로젝트에서 확인해야 합니다.

확인 항목은 다음과 같습니다.

Production deployment = Ready
Production URL 접속 가능
핵심 route 정상
브라우저 console 치명적 오류 없음
필요한 서버 기능 정상

참고용 문서·최소 예제 코드

아래 기존 문서·설정 예시는 변경 이유를 설명합니다. 실제 누적 앱의 전체 소스는 위의 전체 완료 ZIP에 있으며, 다음 회차의 시작본으로 그대로 사용합니다.

완료 체크포인트

deploy-step-04-vercel-production

실습 경로·결과·복구

독자 질문

Vercel 배포 성공 화면 다음에 무엇을 확인해야 할까요?

배포 전제

로컬 npm ci와 npm run build를 통과한 GitHub 저장소, Vercel 접근 권한, 앱이 실제 사용하는 변수 이름 목록이 필요합니다. 3회차 SSH 문서는 선택 확장이고 이 배포의 필수 선행 조건은 1·2회차입니다.

실행 단계

1. GitHub의 대상 저장소와 배포 브랜치를 확인한 뒤 Vercel에서 프로젝트를 가져와 Next.js 프레임워크·루트 디렉터리·build 설정을 실제 저장소와 대조합니다.
2. 앱에서 참조하는 환경변수 이름과 Production 범위만 확인해 등록합니다. 값은 글·스크린샷·Git에 남기지 않습니다. 변경한 환경변수를 사용하려면 새 배포에서 검증합니다.
3. Production deployment의 상태·commit SHA·배포 URL을 기록하고 홈, 주요 작업 화면, 서버/API 경로를 브라우저와 Network 탭에서 각각 확인합니다.

성공·실패 확인

Success와 함께 Production URL에서 핵심 경로가 의도한 응답과 화면을 보이고, 연결된 commit이 기대 버전과 같아야 성공입니다. 빌드 실패면 해당 배포 로그, 200이지만 기능 실패면 runtime 로그와 Network 응답, Preview만 정상이라면 Production 변수 범위를 확인합니다.

복구와 검증 상태

문제가 생기면 먼저 배포 URL과 commit을 보존합니다. 설정 수정 뒤 새 배포를 확인하거나, 이전 정상 deployment가 확인된 경우 플랫폼의 복구 절차로 운영 도메인을 되돌리고 주요 URL을 재검사합니다. 이 글 작성 과정에서 TaskFlow의 실제 Vercel 배포는 미확인입니다.