[{"data":1,"prerenderedAt":710},["ShallowReactive",2],{"blog-vercel-deploy-error-causes":3},{"_path":4,"_dir":5,"_draft":6,"_partial":6,"_locale":7,"title":8,"description":9,"date":10,"category":11,"tags":12,"thumbnail":18,"author":19,"body":20,"_type":704,"_id":705,"_source":706,"_file":707,"_stem":708,"_extension":709},"\u002Fblog\u002Fvercel-deploy-error-causes","blog",false,"","Vercel 배포가 실패할 때 가장 많은 원인 5가지","Vercel 배포 오류, 배포 실패, 하얀 화면, 404의 가장 흔한 원인 다섯 가지와 오류 문구별로 고치는 곳을 정리했어요.","2026-10-02","바이브코딩",[13,14,15,16,17],"vercel 배포 오류","vercel 배포 실패","vercel 404","바이브코딩 배포","환경 변수","\u002Fimages\u002Flanding\u002Fvibe-coding-og.png","날다데브",{"type":21,"children":22,"toc":694},"root",[23,39,46,67,238,244,257,314,320,349,370,376,389,402,487,500,506,519,548,554,628,634,652,658,688],{"type":24,"tag":25,"props":26,"children":27},"element","p",{},[28,31,37],{"type":29,"value":30},"text","Vercel 배포가 실패하는 원인은 대부분 다섯 가지 중 하나예요. ",{"type":24,"tag":32,"props":33,"children":34},"strong",{},[35],{"type":29,"value":36},"환경 변수 누락, 파일 이름 대소문자, 화면 이동(라우팅) 설정, 타입 오류, Node 버전이나 패키지 잠금 파일 문제",{"type":29,"value":38},"예요. 배포 로그 맨 아래의 오류 문장을 보면 어느 쪽인지 바로 알 수 있어요.",{"type":24,"tag":40,"props":41,"children":43},"h2",{"id":42},"먼저-오류-문장을-찾아요",[44],{"type":29,"value":45},"먼저 오류 문장을 찾아요",{"type":24,"tag":25,"props":47,"children":48},{},[49,51,58,60,65],{"type":29,"value":50},"Vercel 프로젝트에서 Deployments → 실패한 배포 → Building 로그를 열어요. ",{"type":24,"tag":52,"props":53,"children":55},"code",{"className":54},[],[56],{"type":29,"value":57},"Error: Command \"npm run build\" exited with 1",{"type":29,"value":59},"은 결과일 뿐이고, 진짜 원인은 ",{"type":24,"tag":32,"props":61,"children":62},{},[63],{"type":29,"value":64},"그 바로 위 몇 줄",{"type":29,"value":66},"에 있어요. 배포는 됐는데 화면이 안 나온다면 사이트에서 F12를 눌러 Console 탭을 봐요.",{"type":24,"tag":68,"props":69,"children":70},"table",{},[71,95],{"type":24,"tag":72,"props":73,"children":74},"thead",{},[75],{"type":24,"tag":76,"props":77,"children":78},"tr",{},[79,85,90],{"type":24,"tag":80,"props":81,"children":82},"th",{},[83],{"type":29,"value":84},"이런 문장이 보이면",{"type":24,"tag":80,"props":86,"children":87},{},[88],{"type":29,"value":89},"원인",{"type":24,"tag":80,"props":91,"children":92},{},[93],{"type":29,"value":94},"바로 아래 번호",{"type":24,"tag":96,"props":97,"children":98},"tbody",{},[99,132,161,185,214],{"type":24,"tag":76,"props":100,"children":101},{},[102,122,127],{"type":24,"tag":103,"props":104,"children":105},"td",{},[106,112,114,120],{"type":24,"tag":52,"props":107,"children":109},{"className":108},[],[110],{"type":29,"value":111},"supabaseUrl is required.",{"type":29,"value":113},", ",{"type":24,"tag":52,"props":115,"children":117},{"className":116},[],[118],{"type":29,"value":119},"undefined",{"type":29,"value":121}," 관련 오류",{"type":24,"tag":103,"props":123,"children":124},{},[125],{"type":29,"value":126},"환경 변수 누락",{"type":24,"tag":103,"props":128,"children":129},{},[130],{"type":29,"value":131},"1",{"type":24,"tag":76,"props":133,"children":134},{},[135,151,156],{"type":24,"tag":103,"props":136,"children":137},{},[138,144,145],{"type":24,"tag":52,"props":139,"children":141},{"className":140},[],[142],{"type":29,"value":143},"Module not found: Can't resolve",{"type":29,"value":113},{"type":24,"tag":52,"props":146,"children":148},{"className":147},[],[149],{"type":29,"value":150},"Could not resolve",{"type":24,"tag":103,"props":152,"children":153},{},[154],{"type":29,"value":155},"파일 이름 대소문자",{"type":24,"tag":103,"props":157,"children":158},{},[159],{"type":29,"value":160},"2",{"type":24,"tag":76,"props":162,"children":163},{},[164,175,180],{"type":24,"tag":103,"props":165,"children":166},{},[167,169],{"type":29,"value":168},"첫 화면은 되는데 새로고침하면 ",{"type":24,"tag":52,"props":170,"children":172},{"className":171},[],[173],{"type":29,"value":174},"404: NOT_FOUND",{"type":24,"tag":103,"props":176,"children":177},{},[178],{"type":29,"value":179},"화면 이동 설정",{"type":24,"tag":103,"props":181,"children":182},{},[183],{"type":29,"value":184},"3",{"type":24,"tag":76,"props":186,"children":187},{},[188,204,209],{"type":24,"tag":103,"props":189,"children":190},{},[191,197,198],{"type":24,"tag":52,"props":192,"children":194},{"className":193},[],[195],{"type":29,"value":196},"Type error:",{"type":29,"value":113},{"type":24,"tag":52,"props":199,"children":201},{"className":200},[],[202],{"type":29,"value":203},"Failed to compile",{"type":24,"tag":103,"props":205,"children":206},{},[207],{"type":29,"value":208},"타입 오류",{"type":24,"tag":103,"props":210,"children":211},{},[212],{"type":29,"value":213},"4",{"type":24,"tag":76,"props":215,"children":216},{},[217,228,233],{"type":24,"tag":103,"props":218,"children":219},{},[220,226],{"type":24,"tag":52,"props":221,"children":223},{"className":222},[],[224],{"type":29,"value":225},"npm ci can only install packages when your package.json and package-lock.json ... are in sync",{"type":29,"value":227},", Node 버전 경고",{"type":24,"tag":103,"props":229,"children":230},{},[231],{"type":29,"value":232},"잠금 파일, Node 버전",{"type":24,"tag":103,"props":234,"children":235},{},[236],{"type":29,"value":237},"5",{"type":24,"tag":40,"props":239,"children":241},{"id":240},"_1-환경-변수가-빠졌어요",[242],{"type":29,"value":243},"1. 환경 변수가 빠졌어요",{"type":24,"tag":25,"props":245,"children":246},{},[247,249,255],{"type":29,"value":248},"가장 흔해요. 내 컴퓨터의 ",{"type":24,"tag":52,"props":250,"children":252},{"className":251},[],[253],{"type":29,"value":254},".env",{"type":29,"value":256}," 파일은 보안 때문에 깃허브에 올라가지 않아서, Vercel은 그 값을 몰라요.",{"type":24,"tag":258,"props":259,"children":260},"ul",{},[261,281,302],{"type":24,"tag":262,"props":263,"children":264},"li",{},[265,267,272,274,279],{"type":29,"value":266},"Settings → Environment Variables에 ",{"type":24,"tag":52,"props":268,"children":270},{"className":269},[],[271],{"type":29,"value":254},{"type":29,"value":273},"의 이름과 값을 ",{"type":24,"tag":32,"props":275,"children":276},{},[277],{"type":29,"value":278},"똑같이",{"type":29,"value":280}," 넣어요.",{"type":24,"tag":262,"props":282,"children":283},{},[284,286,292,294,300],{"type":29,"value":285},"브라우저에서 쓰는 값은 이름 앞에 붙는 말이 정해져 있어요. Next.js는 ",{"type":24,"tag":52,"props":287,"children":289},{"className":288},[],[290],{"type":29,"value":291},"NEXT_PUBLIC_",{"type":29,"value":293},", Vite는 ",{"type":24,"tag":52,"props":295,"children":297},{"className":296},[],[298],{"type":29,"value":299},"VITE_",{"type":29,"value":301},"로 시작해야 화면 코드에서 읽혀요.",{"type":24,"tag":262,"props":303,"children":304},{},[305,307,312],{"type":29,"value":306},"넣은 뒤에는 ",{"type":24,"tag":32,"props":308,"children":309},{},[310],{"type":29,"value":311},"꼭 다시 배포(Redeploy)",{"type":29,"value":313}," 해요. 저장만 하면 이미 만들어진 배포에는 적용되지 않아요.",{"type":24,"tag":40,"props":315,"children":317},{"id":316},"_2-파일-이름-대소문자가-달라요",[318],{"type":29,"value":319},"2. 파일 이름 대소문자가 달라요",{"type":24,"tag":25,"props":321,"children":322},{},[323,325,331,333,339,341,347],{"type":29,"value":324},"맥이나 윈도우는 ",{"type":24,"tag":52,"props":326,"children":328},{"className":327},[],[329],{"type":29,"value":330},"Cart.tsx",{"type":29,"value":332},"와 ",{"type":24,"tag":52,"props":334,"children":336},{"className":335},[],[337],{"type":29,"value":338},"cart.tsx",{"type":29,"value":340},"를 같은 파일로 봐 주지만, Vercel 서버는 다른 파일로 봐요. 그래서 내 컴퓨터에선 되는데 배포에서만 ",{"type":24,"tag":52,"props":342,"children":344},{"className":343},[],[345],{"type":29,"value":346},"Module not found: Can't resolve '.\u002Fcomponents\u002FCart'",{"type":29,"value":348}," 같은 오류가 나요.",{"type":24,"tag":258,"props":350,"children":351},{},[352,357],{"type":24,"tag":262,"props":353,"children":354},{},[355],{"type":29,"value":356},"오류에 나온 경로와 실제 파일 이름을 한 글자씩 비교해요.",{"type":24,"tag":262,"props":358,"children":359},{},[360,362,368],{"type":29,"value":361},"깃은 대소문자만 바꾼 이름 변경을 놓칠 때가 있어서, ",{"type":24,"tag":52,"props":363,"children":365},{"className":364},[],[366],{"type":29,"value":367},"git mv cart.tsx Cart.tsx",{"type":29,"value":369},"처럼 바꿔 주는 게 안전해요.",{"type":24,"tag":40,"props":371,"children":373},{"id":372},"_3-새로고침하면-404가-나요",[374],{"type":29,"value":375},"3. 새로고침하면 404가 나요",{"type":24,"tag":25,"props":377,"children":378},{},[379,381,387],{"type":29,"value":380},"리액트 라우터 같은 화면 이동을 쓰는 Vite 프로젝트는 첫 화면만 진짜 파일이 있고, ",{"type":24,"tag":52,"props":382,"children":384},{"className":383},[],[385],{"type":29,"value":386},"\u002Fabout",{"type":29,"value":388}," 같은 주소는 브라우저 안에서 만들어져요. 그래서 그 주소로 바로 들어오거나 새로고침하면 Vercel이 파일을 못 찾아요.",{"type":24,"tag":25,"props":390,"children":391},{},[392,394,400],{"type":29,"value":393},"프로젝트 맨 위 폴더에 ",{"type":24,"tag":52,"props":395,"children":397},{"className":396},[],[398],{"type":29,"value":399},"vercel.json",{"type":29,"value":401},"을 만들고 아래처럼 넣어 주면 모든 주소를 첫 화면으로 보내 줘요.",{"type":24,"tag":403,"props":404,"children":408},"pre",{"className":405,"code":406,"language":407,"meta":7,"style":7},"language-json shiki shiki-themes github-dark","{\n  \"rewrites\": [{ \"source\": \"\u002F(.*)\", \"destination\": \"\u002F\" }]\n}\n","json",[409],{"type":24,"tag":52,"props":410,"children":411},{"__ignoreMap":7},[412,424,478],{"type":24,"tag":413,"props":414,"children":417},"span",{"class":415,"line":416},"line",1,[418],{"type":24,"tag":413,"props":419,"children":421},{"style":420},"--shiki-default:#E1E4E8",[422],{"type":29,"value":423},"{\n",{"type":24,"tag":413,"props":425,"children":427},{"class":415,"line":426},2,[428,434,439,444,449,455,459,464,468,473],{"type":24,"tag":413,"props":429,"children":431},{"style":430},"--shiki-default:#79B8FF",[432],{"type":29,"value":433},"  \"rewrites\"",{"type":24,"tag":413,"props":435,"children":436},{"style":420},[437],{"type":29,"value":438},": [{ ",{"type":24,"tag":413,"props":440,"children":441},{"style":430},[442],{"type":29,"value":443},"\"source\"",{"type":24,"tag":413,"props":445,"children":446},{"style":420},[447],{"type":29,"value":448},": ",{"type":24,"tag":413,"props":450,"children":452},{"style":451},"--shiki-default:#9ECBFF",[453],{"type":29,"value":454},"\"\u002F(.*)\"",{"type":24,"tag":413,"props":456,"children":457},{"style":420},[458],{"type":29,"value":113},{"type":24,"tag":413,"props":460,"children":461},{"style":430},[462],{"type":29,"value":463},"\"destination\"",{"type":24,"tag":413,"props":465,"children":466},{"style":420},[467],{"type":29,"value":448},{"type":24,"tag":413,"props":469,"children":470},{"style":451},[471],{"type":29,"value":472},"\"\u002F\"",{"type":24,"tag":413,"props":474,"children":475},{"style":420},[476],{"type":29,"value":477}," }]\n",{"type":24,"tag":413,"props":479,"children":481},{"class":415,"line":480},3,[482],{"type":24,"tag":413,"props":483,"children":484},{"style":420},[485],{"type":29,"value":486},"}\n",{"type":24,"tag":25,"props":488,"children":489},{},[490,492,498],{"type":29,"value":491},"Next.js는 이 설정이 필요 없어요. Next.js에서 404가 난다면 파일 위치(",{"type":24,"tag":52,"props":493,"children":495},{"className":494},[],[496],{"type":29,"value":497},"app",{"type":29,"value":499}," 폴더 구조)를 먼저 확인해요.",{"type":24,"tag":40,"props":501,"children":503},{"id":502},"_4-타입-오류로-빌드가-멈춰요",[504],{"type":29,"value":505},"4. 타입 오류로 빌드가 멈춰요",{"type":24,"tag":25,"props":507,"children":508},{},[509,511,517],{"type":29,"value":510},"개발 서버(",{"type":24,"tag":52,"props":512,"children":514},{"className":513},[],[515],{"type":29,"value":516},"npm run dev",{"type":29,"value":518},")는 타입 오류가 있어도 화면을 띄워 주지만, 배포 빌드는 오류가 있으면 멈춰요. 그래서 \"어제까지 잘 되던 게 배포만 안 돼요\"가 생겨요.",{"type":24,"tag":258,"props":520,"children":521},{},[522,535],{"type":24,"tag":262,"props":523,"children":524},{},[525,527,533],{"type":29,"value":526},"내 컴퓨터에서 ",{"type":24,"tag":52,"props":528,"children":530},{"className":529},[],[531],{"type":29,"value":532},"npm run build",{"type":29,"value":534},"를 직접 돌려 보면 같은 오류를 미리 볼 수 있어요.",{"type":24,"tag":262,"props":536,"children":537},{},[538,540,546],{"type":29,"value":539},"오류를 끄는 설정(",{"type":24,"tag":52,"props":541,"children":543},{"className":542},[],[544],{"type":29,"value":545},"ignoreBuildErrors",{"type":29,"value":547},")으로 넘어가면 당장은 올라가도, 실제 기능이 깨진 채로 나갈 수 있어서 권하지 않아요.",{"type":24,"tag":40,"props":549,"children":551},{"id":550},"_5-node-버전이나-잠금-파일이-달라요",[552],{"type":29,"value":553},"5. Node 버전이나 잠금 파일이 달라요",{"type":24,"tag":258,"props":555,"children":556},{},[557,584,608],{"type":24,"tag":262,"props":558,"children":559},{},[560,566,568,574,576,582],{"type":24,"tag":52,"props":561,"children":563},{"className":562},[],[564],{"type":29,"value":565},"package.json",{"type":29,"value":567},"과 ",{"type":24,"tag":52,"props":569,"children":571},{"className":570},[],[572],{"type":29,"value":573},"package-lock.json",{"type":29,"value":575},"이 서로 안 맞으면 설치 단계에서 멈춰요. 내 컴퓨터에서 ",{"type":24,"tag":52,"props":577,"children":579},{"className":578},[],[580],{"type":29,"value":581},"npm install",{"type":29,"value":583},"을 한 번 하고 바뀐 잠금 파일까지 같이 올려요.",{"type":24,"tag":262,"props":585,"children":586},{},[587,592,593,599,600,606],{"type":24,"tag":52,"props":588,"children":590},{"className":589},[],[591],{"type":29,"value":573},{"type":29,"value":113},{"type":24,"tag":52,"props":594,"children":596},{"className":595},[],[597],{"type":29,"value":598},"pnpm-lock.yaml",{"type":29,"value":113},{"type":24,"tag":52,"props":601,"children":603},{"className":602},[],[604],{"type":29,"value":605},"yarn.lock",{"type":29,"value":607},"이 한 폴더에 여러 개 있으면 어떤 걸로 설치할지 헷갈려 해요. 쓰는 것 하나만 남겨요.",{"type":24,"tag":262,"props":609,"children":610},{},[611,613,618,620,626],{"type":29,"value":612},"내 컴퓨터와 Vercel의 Node 버전이 다르면 Settings에서 Node.js Version을 맞추거나, ",{"type":24,"tag":52,"props":614,"children":616},{"className":615},[],[617],{"type":29,"value":565},{"type":29,"value":619},"의 ",{"type":24,"tag":52,"props":621,"children":623},{"className":622},[],[624],{"type":29,"value":625},"engines",{"type":29,"value":627},"에 적어 둬요.",{"type":24,"tag":40,"props":629,"children":631},{"id":630},"혼자-하기-어려운-신호",[632],{"type":29,"value":633},"혼자 하기 어려운 신호",{"type":24,"tag":258,"props":635,"children":636},{},[637,642,647],{"type":24,"tag":262,"props":638,"children":639},{},[640],{"type":29,"value":641},"위 다섯 가지를 다 확인했는데 로그에 처음 보는 오류가 계속 바뀌어 나와요.",{"type":24,"tag":262,"props":643,"children":644},{},[645],{"type":29,"value":646},"하나를 고치면 다른 오류가 생기는 일이 반복돼요.",{"type":24,"tag":262,"props":648,"children":649},{},[650],{"type":29,"value":651},"배포는 됐지만 로그인, 결제, 회원 정보가 이상하게 동작해요. 이건 배포 문제가 아니라 코드 구조 문제일 때가 많아요.",{"type":24,"tag":40,"props":653,"children":655},{"id":654},"막히면-이어서-마무리해-드려요",[656],{"type":29,"value":657},"막히면 이어서 마무리해 드려요",{"type":24,"tag":25,"props":659,"children":660},{},[661,663,670,672,678,680,686],{"type":29,"value":662},"배포 오류는 원인만 찾으면 금방 끝나는 경우가 많아요. 혼자 붙잡고 있기 답답하다면 날다데브가 코드를 보고 고칠 곳을 쉬운 말로 정리해 드려요. 도와드리는 범위는 ",{"type":24,"tag":664,"props":665,"children":667},"a",{"href":666},"\u002Fvibe-coding",[668],{"type":29,"value":669},"바이브코딩 마무리·배포",{"type":29,"value":671},"에서 볼 수 있고, 배포 로그 캡처와 함께 ",{"type":24,"tag":664,"props":673,"children":675},{"href":674},"\u002Fcontact?from=vibe-coding",[676],{"type":29,"value":677},"무료 상담 문의",{"type":29,"value":679},"를 남겨 주세요. 처음부터 순서대로 보고 싶다면 ",{"type":24,"tag":664,"props":681,"children":683},{"href":682},"\u002Fblog\u002Fvibe-coding-deploy-guide",[684],{"type":29,"value":685},"바이브코딩으로 만든 사이트, 인터넷에 올리는 방법",{"type":29,"value":687},"을 먼저 읽어 보세요.",{"type":24,"tag":689,"props":690,"children":691},"style",{},[692],{"type":29,"value":693},"html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}",{"title":7,"searchDepth":426,"depth":426,"links":695},[696,697,698,699,700,701,702,703],{"id":42,"depth":426,"text":45},{"id":240,"depth":426,"text":243},{"id":316,"depth":426,"text":319},{"id":372,"depth":426,"text":375},{"id":502,"depth":426,"text":505},{"id":550,"depth":426,"text":553},{"id":630,"depth":426,"text":633},{"id":654,"depth":426,"text":657},"markdown","content:blog:vercel-deploy-error-causes.md","content","blog\u002Fvercel-deploy-error-causes.md","blog\u002Fvercel-deploy-error-causes","md",1791454319941]