배포 환경 차이 해결: 프록시·캐시·환경변수·헤더 점검

시작 상태

TaskFlow는 다음 상태라고 가정합니다.

Production 배포 성공
주요 route 존재
도메인·HTTPS 정상

하지만
로컬과 Production의 API 결과가 다름
또는 오래된 화면이 보임

목차

1. 문제를 네 계층으로 나누기
2. 환경변수 비교
3. origin과 reverse proxy
4. Cache-Control 확인
5. 캐시된 구버전 확인
6. CORS와 서버 오류 구분
7. 수정 전
8. 수정 후
9. 실습 프로젝트 전체 코드
10. 운영 진단 체크리스트
11. 학습 완료 체크리스트
12. TaskFlow 프로젝트 적용
13. 실습 경로·결과·복구
14. 다음 학습
15. 공식 문서
16. 단독 실습과 결과 확인

문제를 네 계층으로 나누기

환경 차이는 다음 순서로 확인하면 좋습니다.

1. Deployment
현재 URL이 어떤 commit인가

2. Environment
필요한 변수와 URL이 맞는가

3. Network
어디로 요청하고 어떤 상태가 돌아오는가

4. Cache
브라우저/CDN이 이전 응답을 재사용하는가

이 순서를 지키면 “일단 캐시 삭제”, “일단 재배포”처럼 증거가 사라지는 해결 방법부터 적용하는 일을 줄일 수 있습니다.

환경변수 비교

예를 들어 API 주소를 환경변수로 관리한다고 가정합니다.

Development
NEXT_PUBLIC_API_BASE_URL=http://localhost:3000

Preview
NEXT_PUBLIC_API_BASE_URL=https://preview-api.example

Production
NEXT_PUBLIC_API_BASE_URL=https://api.example

코드가 같아도 변수 값이 다르면 요청 결과가 달라집니다.

클라이언트 코드에서는 다음처럼 사용할 수 있습니다.

const apiBaseUrl = process.env.NEXT_PUBLIC_API_BASE_URL;

if (!apiBaseUrl) {
  throw new Error("Missing NEXT_PUBLIC_API_BASE_URL");
}

문제 해결을 위해 실제 Production Secret 값을 console.log로 출력하지 않습니다.

확인해야 할 것은 값 자체가 아니라 다음과 같은 상태입니다.

변수가 존재하는가
올바른 environment scope에 등록되었는가
현재 deployment가 변경된 값을 포함하는가
브라우저 공개 값과 서버 Secret이 구분되었는가

origin과 reverse proxy

origin은 보통 요청을 실제로 처리하는 원본 서버 또는 애플리케이션을 의미합니다.

CDN이나 reverse proxy가 앞에 있다면 사용자의 요청은 바로 origin으로 가지 않을 수 있습니다.

Browser
↓
CDN / Proxy
↓
Origin
↓
Application

이 구조에서는 같은 URL이라도 중간 계층의 캐시나 헤더 정책이 결과에 영향을 줄 수 있습니다.

예를 들어 브라우저 Network 탭에서 다음을 확인합니다.

Request URL
Request Method
Status Code
Origin
Response Headers
Cache-Control
Location

Cache-Control 확인

HTTP Cache-Control 헤더는 브라우저나 공유 캐시가 응답을 어떻게 저장하고 재사용할지 결정하는 데 사용됩니다.

예를 들어 다음 응답은 일정 시간 캐시될 수 있습니다.

Cache-Control: public, max-age=300

반면 민감하거나 항상 최신 상태가 필요한 응답은 다른 정책이 필요합니다.

프로젝트의 데이터 특성을 기준으로 설정해야 하며 모든 API에 no-store를 일괄 적용하는 것도 좋은 기본값은 아닙니다.

문제 해결에서는 먼저 실제 응답 헤더를 봅니다.

$PRODUCTION_URL = Read-Host "본인의 HTTPS Production 주소를 입력하세요"
if ([string]::IsNullOrWhiteSpace($PRODUCTION_URL) -or $PRODUCTION_URL -notmatch "^https://") {
  throw "확인된 HTTPS Production 주소를 입력해야 합니다."
}
$PRODUCTION_URL = $PRODUCTION_URL.TrimEnd("/")
curl.exe -I "$PRODUCTION_URL/"

같은 PowerShell 세션에서 필요하면 API 경로도 확인합니다. HEAD를 지원하지 않아 405가 나온다면 API 고장으로 단정하지 말고 해당 API의 지원 메서드를 확인합니다.

if ([string]::IsNullOrWhiteSpace($PRODUCTION_URL)) {
  throw "먼저 본인의 Production 주소를 설정하세요."
}
curl.exe -I "$PRODUCTION_URL/api/tasks"

캐시된 구버전 확인

사용자가 “수정했는데 그대로다”라고 말할 때 실제로 새 deployment가 Production에 연결되었는지부터 확인합니다.

commit A
→ deployment A
→ 이전 화면

commit B
→ deployment B
→ 수정 화면

현재 도메인이 deployment B를 가리키는지 확인하지 않은 상태에서 브라우저 캐시만 지우면 원인을 놓칠 수 있습니다.

확인 순서는 다음처럼 잡습니다.

1. 현재 Production deployment 확인
2. 해당 deployment의 commit 확인
3. 원본 URL에서 응답 확인
4. custom domain에서 응답 확인
5. 응답 헤더 확인
6. 그다음 브라우저/CDN 캐시 판단

CORS와 서버 오류 구분

CORS는 브라우저가 다른 origin의 응답을 스크립트에서 사용할 수 있는지를 제어하는 보안 메커니즘과 관련됩니다.

하지만 “API 요청이 실패했다”는 모든 상황이 CORS는 아닙니다.

401
→ 인증 문제 가능

403
→ 권한 문제 가능

404
→ URL / route 문제 가능

500
→ 서버 런타임 문제 가능

브라우저 CORS 오류
→ Origin / Access-Control-* 헤더 확인

Network 탭에서 실제 HTTP 응답이 있었는지 확인하고 console 메시지와 함께 판단합니다.

수정 전

환경을 고려하지 않고 API 주소를 코드에 고정했다고 가정합니다.

export const API_BASE_URL = "http://localhost:3000";

로컬에서는 동작하지만 Production 브라우저에서도 localhost를 요청하게 됩니다.

수정 후

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

  return value;
}

export const API_BASE_URL = required(
  "NEXT_PUBLIC_API_BASE_URL",
  process.env.NEXT_PUBLIC_API_BASE_URL,
);

환경별 값은 배포 플랫폼에서 관리합니다. 이전 API_URL 예제에서 API_BASE_URL로 이름을 바꾸었다면 로컬 .env 및 Preview·Production 변수 이름도 함께 맞춘 뒤 다시 빌드합니다. NEXT_PUBLIC_API_BASE_URL에는 끝의 /가 없는 origin을 입력합니다. 공개 환경변수 값은 빌드 시 반영되므로 변경 후 새 빌드가 필요합니다.

운영 진단 체크리스트

문제가 발생했을 때 다음 정보를 먼저 모읍니다.

URL
발생 시각
환경: Preview / Production
deployment ID 또는 URL
commit SHA
HTTP status
browser console
Network request/response
response headers
build/runtime log
DNS 결과가 필요한지 여부

이 정보를 모은 뒤 원인을 하나씩 제거합니다.

학습 완료 체크리스트

• 환경변수를 environment별로 비교할 수 있습니다.
• origin과 proxy 역할을 구분할 수 있습니다.
• Cache-Control 응답을 확인할 수 있습니다.
• 현재 Production deployment와 commit을 확인할 수 있습니다.
• CORS와 일반 HTTP 오류를 구분할 수 있습니다.
• 캐시를 삭제하기 전에 필요한 증거를 수집할 수 있습니다.

AUTH_SECRET=
DEMO_EMAIL=
DEMO_PASSWORD_SALT=
DEMO_PASSWORD_HASH=
SITE_URL=
NEXT_PUBLIC_API_MOCKING=
NEXT_PUBLIC_API_BASE_URL=

# 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에서 재검증

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,
  ),
};

## Runtime difference checklist

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

# 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 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에서 재검증

# 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"
  }
}

# 배포·서버 09 — deploy-step-09-runtime-diff

이 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-08-routing-debug

src/
└─ lib/
   ├─ env.ts
   └─ api.ts

docs/
└─ deployment-plan.md

npm run build

deploy-step-09-runtime-diff

다음 학습

다음 글에서는 오류를 발견한 뒤 빠르게 복구하기 위한 build/runtime 로그, 최소 모니터링, 알림, rollback, incident 기록을 정리합니다.

다음 글: 프론트엔드 운영 모니터링: 로그·알림·롤백·장애 대응

다음 회차 확인 과제: 10회차에서는 수집한 배포 SHA와 로그·응답 기록을 이용해 알림 조건과 안전한 복구 절차를 문서화합니다.

공식 문서

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

• https://vercel.com/docs/environment-variables
• https://vercel.com/docs/logs
• https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Cache-Control
• https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CORS