Next.js Server Component가 예상과 다르게 동작할 때

Next.js 13+의 Server Component는 강력하지만, 예상과 다르게 동작할 때가 많다. 로컬에서는 잘 되던 데이터 페칭이 프로덕션에서는 캐시되고, 때론 아예 실행 안 된다.

먼저 빌드 로그 확인

Next.js 빌드 중에는 Server Component 분석 결과를 출력한다. 어떤 component가 Server Component인지, 뭘 하는지 로그에 나타난다.

npm run build 2>&1 | grep -A5 "Server Components"

혹은 전체 빌드 로그를 본다:

npm run build

빌드 시 경고가 있으면 보통 첫 번째 원인이다. 예를 들어:

• "useEffect is not available in Server Components"
• "The requested module does not provide an export named..."

클라이언트 vs 서버 component 구분

Server Component 파일 최상단에 명시해야 한다:

'use client'; // 클라이언트

export default function MyComponent() { ... }

없으면 기본적으로 Server Component다. 그런데 server component에서 쓸 수 없는 API를 쓰면 빌드나 런타임에 실패한다.

Server Component에서 쓸 수 없는 것들:

• useState, useEffect, useContext 등 hook
• onClick, onChange 등 이벤트 리스너
• localStorage, sessionStorage 등 브라우저 API
• 외부 패키지 중 브라우저 전용 라이브러리

데이터 페칭과 캐싱

Server Component에서의 fetch는 기본적으로 캐시된다. 로컬과 배포 환경에서 캐시 동작이 다를 수 있다.

// 캐시 설정 없음 = 기본 캐시 (배포 환경에서는 최대 기간)
const res = await fetch('https://api.example.com/data');

// 캐시 비활성화
const res = await fetch('https://api.example.com/data', {
  cache: 'no-store'
});

// 60초마다 재검증
const res = await fetch('https://api.example.com/data', {
  next: { revalidate: 60 }
});

로컬 개발 환경(npm run dev)에서는 기본적으로 캐시가 비활성화되지만, 프로덕션(npm run build && npm run start)에서는 캐시가 활성화된다.

데이터가 최신인지 확인

Server Component에서 받은 데이터가 예전 데이터라면, 캐시가 원인이다.

# 프로덕션 빌드 후 실행
npm run build
npm run start

직접 localhost에서 확인하면 캐시 동작을 볼 수 있다. 같은 페이지를 새로고침했을 때:

• 로컬 dev: 매번 데이터 다시 페칭 (최신)
• 프로덕션: 캐시되어 같은 데이터 (오래됨)

기본 캐시 설정 확인

프로젝트 전체의 기본 캐시 설정은 next.config.js에 있을 수 있다.

module.exports = {
  // ISR (Incremental Static Regeneration) 설정
  staticGenerationTimeout: 60,
}

또한 특정 페이지의 캐시를 비활성화하려면 generateStaticParams를 사용한다.

프로덕션 캐시 초기화

배포 후 캐시가 오래된 데이터를 계속 보여준다면, 캐시를 초기화해야 한다.

# on-demand ISR을 사용하는 경우
curl -X POST https://yourapp.com/api/revalidate?secret=your-secret

또는 재배포해서 빌드 캐시를 초기화한다.

배포 후 검증 순서

1. 빌드 로그에서 Server Component 관련 경고 확인
2. 로컬 dev와 prod 빌드에서 동작 비교
3. 데이터 페칭 로직의 캐시 설정 확인
4. 필요시 캐시 재검증 설정 추가
5. 배포 후 데이터가 최신인지 확인

Server Component는 복잡해 보이지만, 빌드 로그와 캐시 설정만 이해하면 대부분의 문제를 해결할 수 있다.