빌드 오류 8시간 삽질 끝에 빛을 보다: Astro 콘텐츠 렌더링 완전 정복!
빌드 오류 8시간 삽질 끝에 빛을 보다: Astro 콘텐츠 렌더링 완전 정복!
개발자에게 오류는 숙명과도 같지만, 가끔은 선을 넘을 때가 있습니다. 제게는 바로 오늘이 그랬습니다. 간단한 블로그 프로젝트를 진행하다 만난 두 가지 오류, 'post.render is not a function' 그리고 'Unable to render Content because it is undefined!'… 이름만 들어도 지긋지긋한 이 녀석들 때문에 저는 장장 8시간을 고통받아야 했습니다.
어둠의 서막: 문제는 어디서부터?
평화롭게 잘 작동하던 개발 환경에 갑자기 나타난 빨간 글씨들. 처음에는 단순한 문법 오류인 줄 알았습니다. 'post.render'라는 함수를 찾을 수 없다고? 분명 콘텐츠 컬렉션에서 가져온 객체에 render 함수가 있다고 배웠는데… 뭐가 문제지?
온갖 검색과 문서를 뒤지기 시작했습니다. Astro 공식 문서부터 시작해 스택오버플로우, 개발 블로그까지… 다양한 시도들이 머릿속을 스쳐 지나갔지만, 해결 기미는 보이지 않았습니다.
끝없는 삽질: 'Content is undefined' 너마저…
'post.render' 문제를 잡았다 싶었더니, 이번에는 'Content is undefined'라는 새로운 오류가 저를 맞이했습니다. 아니, 분명 Astro.props로 잘 받아왔는데 왜 undefined인 거지? 컴포넌트 임포트가 잘못되었나? 오타가 있나? 코드 한 줄 한 줄을 매의 눈으로 살펴보았지만, 이상한 점을 찾을 수 없었습니다.
이 오류를 해결하기 위해 수없이 파일을 열고 닫았습니다. getStaticPaths 함수의 props 전달 방식을 바꿔보고, 페이지 컴포넌트에서 Content를 받아오는 방식을 이리저리 수정해봤습니다. 그럴 때마다 린트 오류가 저를 괴롭혔죠. 마치 ‘넌 틀렸어!’라고 소리치는 것 같았습니다.
시간은 흐르고 흘러, 어느덧 시계를 보니 저녁 8시를 향해 가고 있었습니다. 점심 먹고 앉아서 시작한 이 오류와의 사투가 벌써 8시간째라니… 믿을 수가 없었습니다. 지쳐가는 멘탈과 함께 ‘오늘은 여기까지 해야 하나…’ 하는 생각이 강하게 들었습니다.
한줄기 빛: 공식 문서의 재발견
거의 포기 직전, 마지막으로 Astro 공식 문서의 콘텐츠 컬렉션 가이드를 다시 한번 정독하기 시작했습니다. 특히 ‘Generating Routes from Content’ 섹션을 집요하게 파고들었습니다. 그러다 마침내 결정적인 단서를 발견했습니다.
정적 빌드 시에는 Astro.props에 Content가 자동으로 포함되는 것이 아니라, 페이지 컴포넌트의 setup 스크립트 내에서 astro:content의 render 헬퍼 함수를 사용하여 post 객체를 명시적으로 렌더링해야 Content 컴포넌트를 얻을 수 있다는 사실!
제가 여태까지 Astro.props에서 Content를 바로 구조 분해해서 사용하려 했기에 오류가 발생했던 것입니다. getStaticPaths에서 post 객체를 넘기는 것은 맞았지만, 페이지에서는 await render(post)를 통해 Content를 얻어야 했던 것이죠.
마침내 해결: 8시간의 삽질, 뿌듯함으로…
발견한 내용을 바탕으로 src/pages/[...slug].astro 파일을 수정했습니다. Astro.props에서는 post만 받아오고, js const { Content } = await render(post); 코드를 추가하여 Content 컴포넌트를 얻었습니다. 그리고 다시 빌드…
두근거리는 마음으로 웹사이트를 확인한 순간, 드디어 정상적으로 블로그 글이 표시되는 것을 볼 수 있었습니다! 8시간 동안 저를 괴롭혔던 오류들이 눈 녹듯 사라지는 순간이었습니다.
삽질 기록 요약
| 오류 메시지 | 주요 원인 | 해결 방법 |
|---|---|---|
post.render is not a function | getStaticPaths 또는 페이지에서 post.render() 직접 호출 | render(post) 헬퍼 함수 사용 |
Content is undefined | Astro.props에서 Content 직접 구조 분해 | await render(post) 결과에서 Content 얻기 |
마무리: 삽질도 자산이다
비록 8시간이라는 긴 시간을 오류 해결에 쏟아불었지만, 이번 경험을 통해 Astro의 콘텐츠 컬렉션 작동 방식에 대해 깊이 이해하게 되었습니다. 특히 getStaticPaths, Astro.props, 그리고 render 헬퍼 함수의 정확한 역할을 알게 된 것은 큰 수확입니다.
앞으로는 공식 문서를 더 꼼꼼히 읽고, 작은 기능 하나라도 정확한 사용법을 파악하는 습관을 들여야겠다고 다짐했습니다. 그리고 무엇보다, 어려운 문제에 부딪혔을 때 포기하지 않고 끝까지 파고드는 끈기가 중요하다는 것을 다시 한번 깨달았습니다.
8시간의 삽질은 힘들었지만, 오류를 해결했을 때의 그 뿌듯함은 그 어떤 것과도 바꿀 수 없는 값진 경험이었습니다. 이 글이 저와 비슷한 오류로 고통받는 누군가에게 작은 도움이 되기를 바라며 글을 마칩니다.
#8시간 #Astro빌드 #오류해결기 #개발자일상 #삽질엔딩 #뿌듯