06 · Developer Guide

배포 · 성능 노트Deploy & Performance

Vercel에 PCL 시안을 배포하면서 부딪힌 사고와 그 해법. 사이즈 한도·이미지 정책·로그 추적.

배포 스택

Vercel — pcldesign.kr 자동 배포 (main push)
pnpm — installCommand에서 corepack enable
Next.js 16 — App Router 정적 프리렌더 기본

vercel.jsonjson

{
  "$schema": "https://openapi.vercel.sh/vercel.json",
  "installCommand": "corepack enable && pnpm install --no-frozen-lockfile",
  "buildCommand": "pnpm build"
}

자체호스팅 자산 사이즈 가이드

Vercel 배포 패키지 한도는 약 100MB. public/ 누적 사이즈가 한도에 가까워지면 빌드 성공 후 「Deploying outputs」 단계에서 실패합니다. 아래는 현재 상태입니다.

text

// 자체호스팅 자산 사이즈 가이드 (현재 상태)
public/
├── brand/         24KB     · 로고·CI
├── hero/          364KB    · 홈 슬라이드 3장 (1920×1080 압축)
├── jubo/          8MB      · 주보 4면 × 8호 = 32장 (sips 1400px)
├── hamjul/        25MB     · 12면 × 8호 = 100면 (sips 1400px)
├── qt/            2.9MB    · 2면 × 10일 = 20장 (sips 1200px)
└── news/          14MB     · 평균 19장 × 10건 (sips 1400px)
                  ─────
                   ~50MB    · Vercel 배포 패키지 안전권 (한도 ~100MB)

next.config — 외부 이미지 정책

next/image를 외부 URL과 함께 쓰려면 remotePatterns 등록 필수. 인물 사진(pcltv.org)·유튜브 썸네일이 대표 케이스.

next.config.tsts

// next.config.ts — Tailwind v4 + 이미지 정책
import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  // 외부 이미지 호스트 화이트리스트
  images: {
    remotePatterns: [
      { protocol: "https", hostname: "i.ytimg.com" },        // YouTube 썸네일
      { protocol: "https", hostname: "www.pcltv.org" },      // pcltv 이미지 직접 참조 (인물 사진)
      { protocol: "http", hostname: "www.pcltv.org" },
    ],
  },

  // 실험 옵션 (사용 안 함)
  experimental: {},
};

export default nextConfig;

컬러 토큰 — Tailwind 기본 팔레트 금지

모든 색은 --color-* CSS 변수로. 컴포넌트에서는 text-[color:var(--color-text)] 패턴으로 참조합니다. Tailwind 기본 팔레트(text-gray-500 등)는 디자인 시스템 일관성을 깨므로 사용 금지.

css

/* app/globals.css — 절대 Tailwind 기본 팔레트 쓰지 않음 */
@theme {
  --color-accent: #955E29;            /* PCL Warm Brown */
  --color-text: #1c1916;
  --color-text-muted: #5a544c;
  --color-surface: #fefcf8;
  --color-cream-100: #f5ede0;
  --color-navy-700: #1a2842;
  --color-navy-900: #0F1B2E;
  /* ... */
}

/* 컴포넌트에서 사용 */
className="text-[color:var(--color-text)] bg-[color:var(--color-surface)]"

배포 실패 시 로그 추적

bash

# Vercel 배포 실패 → 로그 확인 순서

# 1) 최근 배포 ID + 상태
gh api 'repos/{owner}/{repo}/deployments?per_page=5' \
  --jq '.[] | "\(.sha[0:7]) \(.created_at)"'

# 2) 실패 배포의 로그
gh api repos/{owner}/{repo}/deployments/{ID}/statuses \
  --jq '.[] | "\(.state) \(.description)"'

# 3) Vercel CLI로 빌드 로그 가져오기
npx vercel inspect dpl_XXX --logs | tail -100

배포 전 체크리스트

npx next build 로컬 성공 (워닝까지 확인)
du -sh public/가 80MB 이하 (한도 안전권)
새로 추가한 자산 경로가 데이터 모듈(lib/preview/*.ts)에 등록됐는지
새 라우트가 NAV(lib/docs/nav.ts 또는 시안 SiblingNav)에 들어갔는지
외부 이미지 호스트 추가 시 next.config.ts remotePatterns
href="#" 같은 비어있는 임시 링크가 남아있지 않은지 (워크플로 ⑤ 활용)