막막한 에러 화면, 이제 무서워하지 마세요! 디자이너를 위한 실전 트러블슈팅 가이드

🚨 "빨간 화면이 떴어요... 이제 어떡하죠?"

지난 포스팅에서 Figma 디자인을 실제 컴포넌트로 변환하는 워크플로우를 다뤘는데요, 실제로 코딩을 하다 보면 예상치 못한 에러들과 마주치게 되죠. 처음엔 정말 막막해요. 하지만 에러는 사실 컴퓨터가 친절하게 알려주는 힌트라는 걸 깨달으면, 오히려 고마운 존재가 될 수 있어요.

오늘은 바이브 코딩을 하면서 꼭 마주치게 될 상황들과 현실적인 해결 방법들을 정리해봤어요. 실제 에러 상황을 예시로 들면서 설명할게요!

🔍 에러 메시지, 이렇게 읽어보세요

1. 핵심만 골라서 읽기

Error: Cannot resolve module './components/Button'
at resolveModuleName (webpack-resolver.js:123)
at resolveModule (webpack-resolver.js:456)

이런 에러를 보면 겁부터 나죠? 하지만 첫 줄만 집중해서 읽어보세요:

• Cannot resolve module './components/Button' → Button 컴포넌트를 찾을 수 없다는 뜻
• 아, 파일 경로가 잘못됐거나 파일명이 틀렸구나!

2. 자주 보는 에러 패턴 익히기

파일 경로 관련:

• Cannot resolve module → 파일을 못 찾겠어요
• Module not found → 모듈이 없어요

문법 관련:

• Unexpected token → 문법에 맞지 않는 코드가 있어요
• Missing semicolon → 세미콜론을 빼먹었어요

React 관련:

• Cannot read property of undefined → 없는 속성에 접근하려고 해요

🤖 AI에게 디버깅 도움 요청하는 법

Claude/ChatGPT에게 효과적으로 질문하기

❌ 나쁜 예시:

"코드가 안 돼요. 도와주세요."

✅ 좋은 예시:

"Next.js 프로젝트에서 Button 컴포넌트를 import하려는데 
'Cannot resolve module ./components/Button' 에러가 나요.

현재 파일 구조:
- pages/index.js (여기서 Button을 import하려고 함)
- components/Button.jsx

사용한 import 코드:
import Button from './components/Button'

어떤 부분을 수정해야 할까요?"

Cursor의 실시간 디버깅 활용하기

Cursor를 사용하고 있다면 정말 편해요:

1. 에러가 발생한 라인에 커서를 두고
2. Cmd + K (또는 Ctrl + K) 눌러서
3. "이 에러를 해결해줘"라고 입력하면
4. 바로 수정된 코드를 제안해줘요!

🔍 구글링 노하우: 검색어가 반이에요

효과적인 검색어 조합

기본 공식: [기술스택] + [에러메시지 핵심단어] + [언어]

실전 예시:

• next.js cannot resolve module 한글
• react component import error
• css module not working nextjs

검색 사이트별 활용법

Stack Overflow: 에러 메시지 전체를 따옴표로 감싸서 검색

"Cannot resolve module ./components/Button"

GitHub Issues: 사용하는 라이브러리명 + 에러 키워드

site:github.com next.js resolve module error

한글 커뮤니티: 개발자스럽, 오키 등에서 "Next.js 에러" 같은 키워드로 검색

💡 실전 트러블슈팅 시나리오

시나리오 1: CSS가 적용 안 될 때

문제상황:

// Button.jsx
import styles from './Button.css'

function Button() {
  return <button className={styles.primary}>버튼</button>
}

해결과정:

1. 에러 메시지 확인 → "Module parse failed"
2. AI에게 질문: "Next.js에서 CSS 파일을 import할 때 Module parse failed 에러가 나요"
3. 답변: CSS Modules을 사용하려면 .module.css 확장자를 써야 함
4. Button.css → Button.module.css로 변경

시나리오 2: 컴포넌트가 렌더링 안 될 때

문제상황: 페이지가 하얗게 나오고 콘솔에 에러

해결과정:

1. 개발자도구 Console 탭 확인
2. "Objects are not valid as a React child" 에러 발견
3. 검색: react objects are not valid as react child
4. 원인 파악: JSX에서 객체를 직접 렌더링하려고 했음
5. 수정: {user} → {user.name}

🛠️ 디버깅할 때 꼭 확인할 체크리스트

기본 점검사항

• 파일명과 import 경로가 정확한가?
• 대소문자가 맞나? (특히 컴포넌트명)
• 필요한 패키지가 설치되어 있나?
• 괄호, 세미콜론이 빠지지 않았나?

Next.js 특화 체크리스트

• pages 폴더 구조가 맞나?
• CSS Modules 확장자가 .module.css인가?
• API 라우트 파일이 pages/api 안에 있나?
• 서버 재시작이 필요한 변경사항은 아닌가?

🚀 막힐 때 멘탈 관리법

1. 작은 단위로 나누기

지난번 프로젝트 구조 설계 포스팅에서 말했듯이, 큰 문제도 작게 나누면 해결할 수 있어요. 에러도 마찬가지예요.

2. 30분 규칙

같은 에러를 30분 이상 붙잡고 있다면, 과감히 도움을 요청하세요. 커뮤니티에 질문하거나 AI에게 다시 물어보세요.

3. 에러 로그 모으기

해결한 에러들을 노션이나 메모앱에 정리해두세요. 나중에 비슷한 에러를 만났을 때 큰 도움이 돼요.

마무리: 에러는 성장의 기회

처음엔 에러가 무섭지만, 하나씩 해결해나가다 보면 어느새 "아, 이 에러구나!" 하면서 금방 고칠 수 있게 돼요. 에러 메시지를 읽고, AI에게 도움을 요청하고, 구글링하는 이 과정 자체가 개발 실력을 키우는 지름길이에요.

다음 포스팅에서는 완성된 프로젝트를 실제로 배포하는 과정을 다뤄볼 예정이에요. 여러분의 첫 사이드프로젝트가 세상에 나오는 순간까지, 함께 가보아요! 💪