🤔 v0 출력만으로 production이 안 되는 이유

v0.dev로 랜딩 페이지를 빠르게 뽑아본 분이라면 다음 단계에서 한 번 막히신 경험이 있을 겁니다. v0 화면 안에서는 깔끔하게 보이는 컴포넌트가 본인 Next.js 프로젝트에 떨어뜨리는 순간 디자인 토큰이 어긋나고, 다크모드가 깨지고, 메타데이터는 비어있고, Lighthouse 점수는 60점대로 내려앉는 상황입니다. 이건 v0의 한계가 아니라 v0의 출력이 "디자인 시안의 React 형태"이지 "본인 프로젝트의 일부"가 아니기 때문이에요.

production-ready로 끌어올리려면 통합 단계에서 6가지 영역을 추가로 손봐야 합니다. App Router 구조에 맞게 라우트와 컴포넌트를 분리하고, 본인 디자인 시스템(보통 shadcn/ui)과 토큰을 맞추고, Next.js 메타데이터 API로 SEO를 채우고, 이미지·폰트·번들 크기를 최적화하고, Analytics와 A/B 테스트를 붙이는 흐름이에요. 이 글은 그 6단계를 실제 코드 패턴으로 정리한 가이드입니다. 비전공자 시각의 v0 사용법은 별도 정리해둔 1시간 랜딩 페이지 가이드에서 먼저 흐름을 잡으신 후 이 글로 통합 단계를 이어가시면 좋아요.

📋 통합 6단계 흐름

단계	작업	예상 시간	산출물
1	v0 export · 의존성 분석	10분	컴포넌트 목록과 외부 의존 라이브러리 정리
2	App Router 라우트와 컴포넌트 분리	15분	`app/(marketing)/page.tsx` + `components/landing/*`
3	shadcn/ui 정합 · 디자인 토큰 매핑	20분	`tailwind.config.ts` 토큰 통일 + 다크모드 정상화
4	메타데이터 API · JSON-LD · OG 이미지	15분	SEO 점수 90점대 진입
5	이미지 · 폰트 · 번들 최적화	20분	LCP 2.5초 이하, CLS 0.1 이하
6	Analytics · A/B 테스트 통합	10분	Vercel Analytics + GrowthBook 또는 Statsig 연결

총 90분 정도면 한 페이지를 production 표준으로 끌어올릴 수 있습니다. 1시간 안에 v0 출력을 받으시고, 이 90분을 더 쓰시면 실제 트래픽을 받을 준비가 끝나는 흐름이에요.

🛠 1단계 — v0 export와 의존성 분석

v0 화면 우측 상단의 코드 보기 → 다운로드를 누르시면 zip 파일이 떨어집니다. 압축을 풀면 보통 app/page.tsx, components/, package.json이 들어있어요. 첫 번째로 봐야 할 건 package.json의 dependencies예요. v0는 lucide-react, class-variance-authority, tailwind-merge 같은 shadcn 호환 패키지를 자동으로 끼워 넣는데, 본인 프로젝트에 이미 같은 라이브러리가 있는지 확인하셔야 합니다. 버전이 다르면 충돌이 나거든요.

# v0 export 후 본인 프로젝트와 비교
diff <(jq -r '.dependencies | keys[]' v0-export/package.json | sort) \
     <(jq -r '.dependencies | keys[]' package.json | sort)

추가로 새로 들어와야 하는 패키지만 추리시고 pnpm add 한 번으로 정리하세요. 이 단계가 끝나면 v0 코드가 본인 프로젝트에서 import 에러 없이 컴파일은 되는 상태가 됩니다.

📦 2단계 — App Router 라우트와 컴포넌트 분리

v0가 출력한 app/page.tsx 한 파일에 Hero, Features, Testimonial, FAQ, Footer가 모두 들어있습니다. App Router에서 production용으로 쓰시려면 이걸 분리해야 해요. 권장 구조는 다음과 같습니다.

app/
├── (marketing)/
│   ├── page.tsx              # 라우트 그룹, 마케팅 레이아웃 분리
│   └── layout.tsx
├── layout.tsx
components/
└── landing/
    ├── hero.tsx
    ├── features.tsx
    ├── testimonial.tsx
    ├── faq.tsx
    └── footer.tsx

라우트 그룹 (marketing)을 두는 이유는 마케팅 페이지(랜딩·가격·about)와 앱 페이지(app/dashboard 등)의 레이아웃을 다르게 가져가기 위해서예요. 마케팅 레이아웃에는 헤더·푸터가 항상 붙고, 앱 레이아웃에는 사이드바가 붙는 식입니다. v0 출력의 한 덩어리 컴포넌트를 의미 단위로 쪼개서 components/landing/ 아래에 두시면 다른 페이지(예: /pricing)에서 같은 Hero 패턴을 재사용하기도 쉬워집니다.

🎨 3단계 — shadcn/ui 정합과 디자인 토큰 매핑

가장 자주 깨지는 부분이에요. v0는 자체 색상 팔레트(예: bg-zinc-900)로 코드를 뽑는데 본인 프로젝트는 보통 shadcn/ui 토큰(bg-background, text-foreground, border-border)을 쓰는 상태입니다. 그대로 두시면 다크모드 토글 시 색상이 바뀌지 않아요.

해결은 v0 출력의 색상 클래스를 shadcn 토큰으로 일괄 치환하시는 겁니다.

// 변환 매핑 예시
// bg-white         → bg-background
// bg-zinc-900      → bg-foreground
// text-black       → text-foreground
// text-zinc-500    → text-muted-foreground
// border-zinc-200  → border-border

복잡한 변환은 shadcn-ui CLI의 add 명령으로 새 컴포넌트를 받으면서 자동 적용되기도 하지만 v0 출력에는 직접 매핑하시는 게 빠릅니다. 마무리로 globals.css의 CSS 변수(--background, --foreground)가 정의되어 있는지 확인하시고, 다크모드 토글로 색상이 정상 반전되는지 한 번 검증하시면 정합이 끝납니다.

🔍 4단계 — 메타데이터 API · JSON-LD · OG 이미지

v0 출력에는 메타데이터가 비어있어요. Next.js 16 App Router의 메타데이터 API로 SEO 기본기를 채우셔야 합니다.

// app/(marketing)/page.tsx
import type { Metadata } from "next";

export const metadata: Metadata = {
  title: "Notely — AI 노트 도구로 회의록 자동 정리",
  description: "회의 음성 녹음 → 30초 만에 요약·할 일·후속 질문까지. Notely는 노트 업무에 특화된 AI 비서입니다.",
  openGraph: {
    title: "Notely — AI 노트 자동 정리",
    description: "회의록을 30초 만에 정리하는 AI 비서",
    images: ["/og-image.png"],
    type: "website",
  },
  twitter: { card: "summary_large_image" },
  alternates: { canonical: "https://example.com/" },
};

Open Graph 이미지는 1200×630 PNG로 public/og-image.png에 두시거나 동적 생성을 위해 app/opengraph-image.tsx를 작성하시는 방법이 있어요. 동적 생성은 Next.js의 ImageResponse를 사용해서 페이지마다 다른 OG 이미지를 만들 수 있습니다. JSON-LD를 추가하시면 검색 결과에 별점·FAQ가 노출될 가능성이 올라가요.

<script
  type="application/ld+json"
  dangerouslySetInnerHTML={{
    __html: JSON.stringify({
      "@context": "https://schema.org",
      "@type": "SoftwareApplication",
      name: "Notely",
      applicationCategory: "ProductivityApplication",
      operatingSystem: "Web",
      offers: { "@type": "Offer", price: "0", priceCurrency: "USD" },
    }),
  }}
/>

⚡ 5단계 — 이미지 · 폰트 · 번들 최적화

LCP(Largest Contentful Paint)와 CLS(Cumulative Layout Shift)는 Vercel Analytics 점수와 검색 순위에 직접 영향을 줍니다. 세 가지를 손보시면 평균 60점대에서 90점대로 올라가요.

첫째, 이미지는 반드시 next/image의 Image 컴포넌트로 바꾸세요. v0가 출력한 일반 <img> 태그를 Image로 바꾸시고 Hero에 들어가는 첫 이미지는 priority 속성을 명시하세요. LCP 점수가 즉시 개선됩니다.

둘째, 폰트는 next/font/google로 self-host하셔야 해요. v0가 추천하는 Inter 폰트도 그대로 외부 fetch로 두면 CLS가 발생합니다.

// app/layout.tsx
import { Inter } from "next/font/google";

const inter = Inter({ subsets: ["latin"], display: "swap" });

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="ko" className={inter.className}>
      <body>{children}</body>
    </html>
  );
}

셋째, 번들 사이즈는 @next/bundle-analyzer로 점검하세요. v0가 끼워 넣은 라이브러리 중 안 쓰는 게 있으면 제거하시고, 큰 라이브러리(예: framer-motion)는 동적 import로 분리하시는 게 좋습니다.

📊 6단계 — Analytics와 A/B 테스트 통합

마지막 단계는 운영입니다. 트래픽이 들어와도 측정이 없으면 다음 가설을 세울 수 없어요. 가장 가성비 좋은 조합은 Vercel Analytics + GrowthBook입니다.

// app/layout.tsx
import { Analytics } from "@vercel/analytics/next";
import { SpeedInsights } from "@vercel/speed-insights/next";

export default function RootLayout({ children }) {
  return (
    <html lang="ko">
      <body>
        {children}
        <Analytics />
        <SpeedInsights />
      </body>
    </html>
  );
}

@vercel/analytics는 페이지뷰·이벤트를, @vercel/speed-insights는 Core Web Vitals를 자동 수집해요. A/B 테스트가 필요하시면 GrowthBook 또는 Statsig의 SDK를 추가하시고 Hero 헤드라인 변형 2-3개를 사용자에게 무작위 노출 → 클릭률 비교 흐름을 만드시면 됩니다. 첫 트래픽 1,000명까지는 단순 페이지뷰만 보시고, 그 이후 A/B 테스트를 시작하시는 게 통계적 의미가 생깁니다.

✅ 통합 완료 점검 목록

pnpm build가 0개 에러로 끝나는가
다크모드 토글 시 모든 색상이 정상 반전되는가
Hero 이미지가 priority 속성으로 즉시 로드되는가
next/font로 폰트가 self-host되어 있고 CLS가 0.1 이하인가
메타데이터·OG 이미지·JSON-LD 모두 적용되어 있는가
Vercel Analytics와 Speed Insights가 데이터 수집을 시작했는가
모바일 viewport 375px에서 레이아웃이 깨지지 않는가
Lighthouse 점수가 90점대인가

7개 이상 체크되면 production 통합이 완료된 상태입니다. 8개 모두 체크되면 Web Vitals가 검색 순위에 긍정적 신호를 줄 수 있어요. Vercel 배포 흐름이 처음이시면 별도 정리해둔 Vercel 무료 배포 가이드를 참고하시면 도움이 됩니다.

🧩 자주 막히는 4가지 상황과 진단

상황 1 — 다크모드에서 일부 텍스트가 흰 배경에 흰 글씨로 안 보임. v0 출력에 남아있는 text-white 같은 절대 색상 클래스가 원인입니다. 모든 절대 색상을 shadcn 토큰(text-foreground, text-muted-foreground 등)으로 치환하시면 해결됩니다.

상황 2 — Hero 이미지가 늦게 뜨고 LCP가 4초가 넘음. <img> 태그를 그대로 둔 경우입니다. next/image의 Image 컴포넌트로 바꾸시고 priority 속성을 추가하세요. 이미지가 외부 URL이면 next.config.js의 images.remotePatterns에도 도메인을 등록하셔야 합니다.

상황 3 — pnpm build에서 "Module not found" 에러. v0가 import한 라이브러리가 본인 프로젝트에 없는 경우입니다. 1단계의 의존성 분석을 다시 돌리시고 누락된 패키지를 pnpm add로 추가하세요.

상황 4 — 메타데이터 API가 동작하지 않음. App Router가 아닌 Pages Router 프로젝트에 v0 출력을 떨어뜨린 경우 발생합니다. app/ 디렉토리 구조인지 먼저 확인하시고, App Router로 전환하시거나 Pages Router용 next/head로 메타데이터를 작성하셔야 해요.

⚖️ v0 vs Claude Design vs 직접 작성 — 언제 무엇을

도구	강점	약점	추천 상황
v0.dev	React+Tailwind 출력 즉시, shadcn 호환	자체 디자인 토큰과 본인 프로젝트의 정합 작업 필요	Next.js 프로젝트에 빠르게 한 페이지 추가
Claude Design	빠른 프로토타입, 다양한 출력 형식	출력 형식이 React 외에도 섞여 있어 통합 단계가 더 김	디자인 시안을 단순 미리보기로 보고 싶을 때
직접 작성	최대 커스텀, 의존성 0	시간 비용 가장 큼	본인 디자인 시스템이 강하게 정립된 팀

비전공자 시각의 도구 비교는 별도 정리해둔 Claude Design 사용법 가이드에서 더 자세히 다뤘습니다. 개발자 입장에서는 "v0 출력 → Next.js 통합" 흐름이 가장 효율적이라는 것이 이 글의 핵심 결론입니다.

💡 운영 팁 3가지

팁 1 — v0 export 전에 한 섹션씩 완성하세요. 한 번에 페이지 전체를 시키지 마시고 Hero → 미리보기 → Features → 미리보기 식으로 끊어서 작업하시면 후속 통합이 훨씬 쉬워집니다. v0 화면 안에서 한 섹션이 마음에 들 때 export하시고 본인 프로젝트로 옮기는 흐름이 마찰이 가장 적어요.

팁 2 — Tailwind 토큰은 복사 후 일괄 치환 스크립트로 정리하세요. v0 출력 코드의 색상 클래스는 패턴이 일정해서 sed 또는 VS Code의 정규식 검색으로 한 번에 치환할 수 있습니다. 매번 손으로 바꾸지 마시고 변환 매핑 시트를 한 번 만들어두시면 다음 v0 출력 통합도 5분 안에 끝납니다.

팁 3 — Lighthouse 점수는 production 배포 후에 측정하세요. 로컬에서 보는 점수와 Vercel production 배포 후의 점수가 다릅니다. 통합 완료 후 반드시 Vercel preview URL에서 한 번 측정하시고, 90점 미만이면 5단계 최적화로 돌아가세요.

면책조항: 이 글은 2026년 5월 기준 v0.dev v1, Next.js 16, shadcn/ui 3.x, Vercel Analytics 2.x를 기준으로 작성됐습니다. 도구 버전이 업데이트되면 일부 API와 디렉토리 구조가 달라질 수 있으니 작업 전 각 도구의 공식 문서로 최신 사용법을 확인하시기 바랍니다. 본 글의 6단계 워크플로는 일반적 통합 패턴을 정리한 가이드이며 모든 프로젝트에 동일하게 적용되지는 않습니다.

여기까지 읽어주셔서 감사드려요. v0는 디자인 시안을 빠르게 꺼내는 도구이고, 진짜 가치는 그 시안을 본인 production 프로젝트로 끌어올리는 통합 흐름에 있습니다. 이 6단계를 한 번 익혀두시면 다음 랜딩 페이지·가격 페이지·about 페이지 모두 90분이면 production 표준으로 올릴 수 있어요.

❓ 자주 묻는 질문

Q. v0 무료 플랜으로 production 통합까지 가능한가요?

가능합니다. v0 무료 플랜은 월 메시지 한도만 있고 출력 코드의 사용·수정에는 제약이 없습니다. 1-3단계는 무료 플랜으로 충분히 처리되고, 4-6단계는 Next.js·Vercel 영역이라 v0 플랜과 무관해요.

Q. v0 출력을 그대로 production에 올려도 되나요?

권장하지 않습니다. 이 글의 6단계 중 최소 3·4단계(shadcn 정합·메타데이터)는 거치셔야 다크모드와 SEO가 정상 동작합니다. 5단계(성능 최적화)는 트래픽이 늘어난 후에 보강해도 되지만 SEO는 처음부터 채우시는 게 좋습니다.

Q. 본인 프로젝트가 Pages Router면 어떻게 통합하나요?

App Router용 메타데이터 API 대신 next/head로 메타데이터를 작성하시고, 라우트 그룹 (marketing) 대신 pages/index.tsx에 직접 두시면 됩니다. 다만 새 프로젝트라면 처음부터 App Router로 시작하시는 걸 권장드려요. v0 출력도 App Router 기준으로 나옵니다.

Q. shadcn/ui를 안 쓰는 프로젝트에서는 3단계가 어떻게 달라지나요?

본인 프로젝트의 디자인 토큰(예: bg-primary, text-secondary)으로 v0 출력의 절대 색상을 치환하시면 됩니다. CSS 변수로 토큰을 관리하시면 다크모드도 자동으로 적용돼요. shadcn/ui가 토큰 관리의 표준 패턴을 제공할 뿐이고, 같은 원리는 본인 디자인 시스템에도 적용됩니다.

Q. v0 출력 코드의 라이선스는 어떻게 되나요?

v0의 출력 코드는 사용자 본인 소유로 자유롭게 수정·배포·상업 이용이 가능합니다. 공식 약관에 명시되어 있으며 production 사용에 별도 제약이 없습니다. 다만 v0가 사용하는 폰트·아이콘 라이브러리는 각자의 라이선스를 따릅니다.

Q. A/B 테스트는 처음부터 붙여야 하나요?

처음 1,000명 트래픽까지는 페이지뷰만 보시는 걸 권장드립니다. 그 미만에서는 통계적 유의성이 안 나와서 A/B 테스트 결과를 신뢰하기 어려워요. Vercel Analytics로 페이지뷰·이탈률만 보시고, 1,000명 넘어간 후 GrowthBook 또는 Statsig로 헤드라인 A/B를 시작하세요.

Q. v0 통합 후 디자인이 어색하면 어떻게 다듬나요?

v0 화면으로 돌아가셔서 해당 섹션만 다시 다듬어 export하시는 게 가장 빠릅니다. 본인 프로젝트 안에서 직접 수정하면 v0가 만든 일관성이 깨지기 쉬워요. 큰 변경은 v0 안에서, 작은 색상·간격 조정은 본인 프로젝트 안에서 하시는 식으로 분리하시면 됩니다.

Q. OG 이미지는 매번 따로 만들어야 하나요?

페이지마다 다르게 보이게 하시려면 app/opengraph-image.tsx로 동적 생성하세요. Next.js의 ImageResponse를 사용하면 페이지 제목·설명·아이콘을 받아 동적으로 1200×630 이미지를 생성합니다. 한 페이지 짜리 랜딩이라면 정적 PNG 1장으로도 충분해요.

v0 출력 코드를 production Next.js에 통합하는 6단계 — App Router·shadcn·메타데이터·성능 (2026)