프론트엔드 배포 오류 해결 허브: Vercel, Netlify, Firebase 체크리스트

가장 먼저 기록할 정보

장애가 발생하면 새 deployment를 만들거나 설정을 바꾸기 전에 현재 상태를 기록합니다.

발생 URL
발생 시각
환경: Preview / Production
deployment
commit SHA
HTTP status
브라우저 console
Network 요청
build log
runtime log
DNS 결과
response headers

모든 문제에 모든 정보가 필요한 것은 아닙니다.

하지만 현재 deployment와 commit, 실제 URL, status는 대부분의 배포 장애에서 중요한 시작점이 됩니다.

Install 오류

대표 증상은 다음과 같습니다.

npm ci 실패
lockfile error
dependency resolution error
package manager command not found

첫 확인 지점:

package.json
package-lock.json
Node/npm 버전
package manager
.npmrc
CI install command

진단 순서:

npm ci 로컬 재현
↓
package.json / lockfile diff
↓
Node 버전 비교
↓
package manager 혼용 확인
↓
CI 재실행

install 오류가 해결되기 전에는 route나 DNS를 볼 필요가 없습니다.

Build 오류

대표 증상:

TypeScript error
Next.js build failed
Missing environment variable
page generation error

첫 확인 지점:

build log의 최초 오류
npm run build 로컬 재현
Production env
Node runtime
Root Directory
build command

“Build failed with exit code 1”만 보는 것이 아니라 그 앞의 실제 오류를 찾습니다.

Runtime 오류

deployment는 Ready인데 기능이 실패합니다.

페이지 일부 500
Route Handler 실패
DB/API 연결 실패
로그인 요청 실패

첫 확인 지점:

runtime log
Network status
server env
외부 API/DB 응답
인증/권한

build가 성공했다는 사실은 runtime 정상까지 보장하지 않습니다.

404와 routing

다음 순서로 구분합니다.

1. Production 기본 URL에서도 같은가
2. route 파일이 실제로 존재하는가
3. rewrite/redirect 목적지가 존재하는가
4. 정적 asset만 실패하는가
5. custom domain에서만 실패하는가

예를 들어 다음이면 DNS보다 route를 먼저 봅니다.

/
→ 200

/tasks
→ 404

반대로 Vercel 기본 URL은 정상인데 custom domain 전체가 다른 프로젝트의 404를 반환한다면 domain 연결을 확인합니다.

DNS와 HTTPS

대표 증상:

도메인이 열리지 않음
DNS_PROBE 오류
인증서 대기
HTTPS 경고
www와 apex 결과가 다름

확인 순서:

DNS record
↓
공개 DNS 조회
↓
플랫폼 domain 상태
↓
TLS certificate
↓
HTTP response

DNS 변경 직후에는 cache와 TTL 때문에 resolver마다 다른 결과가 보일 수 있습니다.

CORS와 proxy

브라우저 console에 CORS 관련 메시지가 보이면 실제 요청 URL과 응답 헤더를 함께 확인합니다.

Origin
Access-Control-Allow-Origin
Request URL
Status Code
Redirect

하지만 API가 500을 반환한 뒤 CORS 헤더가 없어서 브라우저에서 CORS처럼 보이는 경우도 있을 수 있습니다.

따라서 Network와 서버 로그를 함께 봅니다.

브라우저 메시지
+
실제 HTTP 응답
+
서버 로그

캐시된 구버전

대표 증상:

새 코드가 배포됐는데 화면은 이전 상태
특정 사용자만 오래된 화면
asset이 이전 hash를 요청

확인 순서:

현재 Production deployment
↓
commit SHA
↓
원본 deployment URL
↓
custom domain
↓
response headers
↓
browser/CDN cache

원인을 확인하기 전에 모든 캐시를 지우면 문제를 재현할 증거를 잃을 수 있습니다.

500과 서버 오류

500은 서버에서 요청 처리 중 오류가 발생했다는 신호입니다.

확인 항목:

runtime log
환경변수
DB/API 연결
server-only code
request input
authentication
external dependency

Production Secret을 console에 출력해서 확인하지 않습니다.

존재 여부나 어떤 단계에서 실패했는지만 안전하게 로그로 남깁니다.

증상별 빠른 표

이 표는 원인을 확정하는 표가 아니라 첫 조사 위치를 정하는 표입니다.

수정 후 검증

문제 원인을 수정한 뒤에는 단순히 deployment가 Ready인지 확인하고 끝내지 않습니다.

1. 새 deployment 확인
2. 해당 commit 확인
3. 문제가 발생한 URL 재검증
4. 핵심 route smoke test
5. 핵심 API 확인
6. console/runtime log 확인
7. 다른 주요 기능 회귀 확인

rollback 판단

다음 조건에서는 수정 완료를 기다리는 것보다 이전 정상 deployment로 복구하는 방안을 검토할 수 있습니다.

Production 전체 사용자 영향
핵심 기능 사용 불가
원인 분석에 시간이 필요
이전 deployment가 정상임을 알고 있음
rollback이 데이터 정합성을 깨뜨리지 않음

DB schema나 데이터 구조가 새 버전에서 변경되었다면 프론트엔드 deployment만 되돌려도 안전한지 별도 확인해야 합니다.

최종 배포 체크리스트

배포 전

npm ci
npm run build
CI 확인
환경변수 확인
Secret commit 여부 확인

배포 직후

Production deployment
commit SHA
homepage
핵심 route
핵심 API
auth
browser console
runtime log

도메인

DNS
HTTPS
canonical domain
redirect
auth callback / allowed origin

운영

현재 deployment 확인 가능
build/runtime log 확인 가능
rollback runbook 존재
incident template 존재
핵심 smoke test 정의

학습 완료 체크리스트

• 배포 장애를 계층별로 분류할 수 있습니다.
• 증상별 첫 확인 위치를 정할 수 있습니다.
• 수정 전 deployment와 commit을 기록할 수 있습니다.
• build와 runtime 오류를 구분할 수 있습니다.
• DNS와 route 404를 구분할 수 있습니다.
• cache 문제를 증거 기반으로 확인할 수 있습니다.
• 필요할 때 rollback을 검토할 수 있습니다.

# TaskFlow 최종 배포 점검표

이 문서는 점검 절차입니다. 실제 Production 배포 완료나 정상 동작을 증명하는 기록이 아닙니다.

## 배포 전
- [ ] npm ci 통과
- [ ] npm run build 통과
- [ ] CI 실행 결과 확인
- [ ] 환경 변수 scope 확인
- [ ] 비밀값 commit 여부 점검

## 배포 직후
- [ ] Production deployment와 commit SHA 확인
- [ ] 홈페이지와 핵심 route 응답 확인
- [ ] 핵심 API와 인증 흐름 확인
- [ ] 브라우저 console 및 runtime log 확인

## 도메인
- [ ] DNS와 HTTPS 확인
- [ ] canonical domain과 redirect 확인
- [ ] auth callback 및 allowed origin 확인

## 운영
- [ ] deployment와 로그 확인 경로 문서화
- [ ] rollback runbook 검토
- [ ] incident template 준비
- [ ] 핵심 smoke test 정의

# 7편 NEXT_PUBLIC_API_URL을 이 회차부터 NEXT_PUBLIC_API_BASE_URL로 통일합니다.
# 끝에 /가 없는 API origin을 설정하세요. 공개 API 주소만 넣고 secret은 넣지 마세요.
NEXT_PUBLIC_API_BASE_URL=
API_SECRET=

name: CI


on:
  push:
    branches:
      - main
  pull_request:


jobs:
  build:
    runs-on: ubuntu-latest


    steps:
      - name: Checkout
        uses: actions/checkout@v7


      - name: Setup Node.js
        uses: actions/setup-node@v7
        with:
          node-version: "24.x"
          cache: "npm"


      - name: Install dependencies
        run: npm ci


      - name: Build
        run: npm run build

node_modules/
.next/
.env.local
*.tsbuildinfo

24

import type { ReactNode } from "react";
export default function RootLayout({ children }: { children: ReactNode }) {
  return <html lang="ko"><body>{children}</body></html>;
}

import Link from "next/link";
export default function Home() {
  return <main><h1>TaskFlow 배포 진단 실습</h1><Link href="/tasks">작업 목록</Link></main>;
}

export default function TasksPage() {
  return (
    <main>
      <h1>Tasks</h1>
      <p>TaskFlow 작업 목록입니다.</p>
    </main>
  );
}

# TaskFlow 최종 배포 점검표

이 문서는 점검 절차입니다. 실제 Production 배포 완료나 정상 동작을 증명하는 기록이 아닙니다.

## 배포 전
- [ ] npm ci 통과
- [ ] npm run build 통과
- [ ] CI 실행 결과 확인
- [ ] 환경 변수 scope 확인
- [ ] 비밀값 commit 여부 점검

## 배포 직후
- [ ] Production deployment와 commit SHA 확인
- [ ] 홈페이지와 핵심 route 응답 확인
- [ ] 핵심 API와 인증 흐름 확인
- [ ] 브라우저 console 및 runtime log 확인

## 도메인
- [ ] DNS와 HTTPS 확인
- [ ] canonical domain과 redirect 확인
- [ ] auth callback 및 allowed origin 확인

## 운영
- [ ] deployment와 로그 확인 경로 문서화
- [ ] rollback runbook 검토
- [ ] incident template 준비
- [ ] 핵심 smoke test 정의

# 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: 확인

## Domain


- canonical domain: 운영 문서에서 관리
- www policy: canonical로 redirect
- HTTPS: 확인
- DNS status: 확인
- auth callback / allowed origin: 확인

## Runtime difference checklist


1. Production deployment와 commit 확인
2. 환경변수 이름·scope 확인
3. Request URL과 status 확인
4. Response headers 확인
5. origin / proxy 경로 확인
6. cache 여부 확인
7. 수정 후 새 deployment에서 재검증

# Incident


## Summary


## Started


## Impact


## Evidence


## Root cause


## Recovery


## Verification


## Prevention

# TaskFlow Rollback Runbook


## Before rollback
1. 현재 deployment 기록
2. 현재 commit 기록
3. 사용자 영향 확인
4. 로그와 status 확보


## Rollback
- 이전 정상 deployment를 선택
- 운영 트래픽을 정상 버전으로 전환


## After rollback
1. 홈페이지 확인
2. 핵심 route 확인
3. 주요 API 확인
4. 인증 흐름 확인
5. 환경변수·외부 서비스 영향 확인

6. Vercel Instant Rollback 후 Production 도메인 자동 할당 상태를 확인한다. 정상 deployment를 승격하거나 Undo Rollback으로 자동 배포를 재개한다.

# 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

/// <reference types="next" />
/// <reference types="next/image-types/global" />
import "./.next/types/routes.d.ts";
import "./.next/types/root-params.d.ts";

// NOTE: This file should not be edited
// see https://nextjs.org/docs/app/api-reference/config/typescript for more information.

import type { NextConfig } from "next";


const nextConfig: NextConfig = {
  async rewrites() {
    return [
      {
        source: "/legacy/tasks",
        destination: "/tasks",
      },
    ];
  },
};


export default nextConfig;

{
  "name": "taskflow-deployment-lab",
  "private": true,
  "engines": {
    "node": "24.x"
  },
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "typecheck": "tsc --noEmit"
  },
  "dependencies": {
    "next": "16.3.5",
    "react": "19.3.0",
    "react-dom": "19.3.0"
  },
  "devDependencies": {
    "typescript": "5.9.3",
    "@types/node": "24.10.1",
    "@types/react": "19.2.7",
    "@types/react-dom": "19.2.3"
  }
}

# 배포·서버 11 — deploy-step-11-production-final

이 ZIP은 8편의 /legacy/tasks → /tasks rewrite를 재현하는 최소 Next.js 앱과 이전 회차 운영 문서를 포함합니다. 기존 TaskFlow 전체 기능, 로그인, 실제 API 서버나 Production 배포 상태를 제공하지 않습니다.

Node.js 24.x, npm을 사용합니다. `npm ci` → `npm run typecheck` → `npm run build`로 확인하고 `npm run dev` 후 `/tasks`, `/legacy/tasks`를 비교합니다. 전체 의존성 잠금 파일은 package-lock.json에 있습니다.

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

CI workflow는 이미 package.json/package-lock.json과 build 스크립트가 있는 기존 npm 프로젝트 루트에 적용합니다. actions/checkout@v7, actions/setup-node@v7, Node 24.x를 사용합니다. GitHub 원격 실행은 검증하지 않았습니다.

src/lib/env.ts는 해당 모듈을 import할 때 환경 변수를 검사합니다. 파일을 추가하기만 해서는 사용하지 않는 앱 전체의 환경 설정이 자동 검증되지 않습니다.

9편부터 변수명을 NEXT_PUBLIC_API_BASE_URL로 통일합니다. 7편 NEXT_PUBLIC_API_URL 값의 이름을 바꾸고 Preview/Production scope에도 반영한 뒤 다시 build해야 합니다. 끝에 /가 없는 API origin을 입력하세요. src/lib/api.ts의 getTasks는 독자의 실제 /api/tasks API를 호출하는 함수이며 이 최소 앱에는 API 서버와 호출 UI를 추가하지 않았습니다.

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

import { env } from "./env";


export async function getTasks() {
  const response = await fetch(`${env.apiBaseUrl}/api/tasks`);


  if (!response.ok) {
    throw new Error(`Failed to fetch tasks: ${response.status}`);
  }


  return response.json();
}

function required(name: string, value: string | undefined) {
  if (!value) {
    throw new Error(`Missing environment variable: ${name}`);
  }


  return value;
}


export const env = {
  apiBaseUrl: required(
    "NEXT_PUBLIC_API_BASE_URL",
    process.env.NEXT_PUBLIC_API_BASE_URL,
  ),
};

{
  "compilerOptions": {
    "target": "ES2017",
    "lib": [
      "dom",
      "dom.iterable",
      "esnext"
    ],
    "allowJs": true,
    "skipLibCheck": true,
    "strict": true,
    "noEmit": true,
    "esModuleInterop": true,
    "module": "esnext",
    "moduleResolution": "bundler",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "jsx": "react-jsx",
    "incremental": true,
    "plugins": [
      {
        "name": "next"
      }
    ],
    "paths": {
      "@/*": [
        "./*"
      ]
    }
  },
  "include": [
    "next-env.d.ts",
    "**/*.ts",
    "**/*.tsx",
    ".next/types/**/*.ts",
    ".next/dev/types/**/*.ts"
  ],
  "exclude": [
    "node_modules"
  ]
}

deploy-step-10-observability-rollback

docs/
├─ deployment-plan.md
├─ server-access-runbook.md
├─ rollback-runbook.md
└─ incident-template.md

GitHub 저장소
↓
CI clean install / build
↓
Production deployment
↓
custom domain / HTTPS
↓
route / env / runtime 검증
↓
logs / smoke test
↓
rollback / incident response

deploy-step-11-production-final

증상 → 계층 분류 → 증거 수집 → 최소 수정 → 재배포/rollback → 회귀 확인

다음 학습

배포 과정에서 만든 deployment plan, runbook, incident 기록은 이후 AI 코딩 도구 과정에서 에이전트의 작업 범위와 검증 조건으로 사용할 수 있고, 업무·자동화 과정에서는 재시도·알림·실패 복구 설계의 실제 사례로 연결할 수 있습니다.

다음 회차 확인 과제: 다음 과정에서는 이 배포 계획과 incident 기록을 AI 코딩 도구 또는 업무 자동화의 작업 범위·운영 인수 자료로 재사용합니다.

공식 문서

공식 문서 확인 기준: 2026-09-21

• https://vercel.com/docs/deployments
• https://vercel.com/docs/logs
• https://vercel.com/docs/environment-variables
• https://vercel.com/docs/domains
• https://nextjs.org/docs/app/api-reference/config/next-config-js/rewrites
• https://docs.npmjs.com/cli/commands/npm-ci/
• https://firebase.google.com/docs/hosting
• https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Cache-Control