화면 깜빡임은 겉보기엔 하나지만 원인이 완전히 다른 두 가지가 섞여 있습니다. 어느 쪽인지부터 구분하면 90%는 해결됩니다.

1단계: 어떤 깜빡임인지 먼저 구분하세요

  • A. 처음 켤 때 딱 한 번 반짝: 페이지가 뜨는 순간 흰 화면이 보였다가 다크모드로 바뀌거나, 로그인 안 된 화면이 잠깐 보였다가 진짜 화면으로 바뀝니다. → 대부분 하이드레이션 미스매치 또는 테마 플래시.
  • B. 멈추지 않고 계속 깜빡깜빡: 화면이 계속 떨리거나 무한 새로고침되는 느낌이고, 탭이 느려지며 노트북 팬이 돕니다. → 대부분 무한 리렌더 루프.

확실히 구분하려면 브라우저에서 F12(개발자 도구) → Console 탭을 열어 빨간 에러를 보세요.

  • Hydration failed / Text content did not match → A
  • Maximum update depth exceeded → B

---

B. 계속 깜빡인다: 무한 리렌더 루프 (가장 흔함)

콘솔에 Maximum update depth exceeded가 뜨면 확정입니다. 원인은 거의 항상 하나입니다 — useEffect 안에서 상태(state)를 바꾸는데, 그 바뀐 상태가 다시 useEffect를 실행시켜 무한 반복됩니다.

AI(커서·v0·볼트 등)에게 이렇게 요청하세요 (복붙)

Console에 Maximum update depth exceeded 에러가 나면서 화면이 계속 깜빡여요. useEffect 안에서 setState를 호출하는데 의존성 배열(dependency array)이 잘못돼서 무한 루프가 도는 것 같아요. 어떤 useEffect가 원인인지 찾아서, 의존성 배열을 고치거나 업데이터 함수(setCount(c => c + 1)) 형태로 바꿔주세요. 임시로 감추지 말고 근본 원인을 잡아주세요.

직접 코드를 볼 수 있다면 (React 공식 권장 수정 2가지)

1) 이전 값 기반 업데이트로 바꾸기 — 의존성 제거

js

// 문제: count가 바뀔 때마다 effect가 다시 돌아 무한 루프
useEffect(() => {
  setCount(count + 1);
}, [count]);

// 해결: 업데이터 함수 사용 + 의존성 비우기
useEffect(() => {
  setCount(c => c + 1);
}, []);

2) 객체·함수를 의존성으로 쓰지 말고 effect 안에서 만들기

js

// 문제: options 객체가 매 렌더마다 새로 만들어져 무한 루프
const options = { serverUrl, roomId };
useEffect(() => {
  createConnection(options);
}, [options]);

// 해결: effect 안에서 만들기
useEffect(() => {
  const options = { serverUrl, roomId };
  createConnection(options);
}, [roomId, serverUrl]);

핵심 체크: useEffect(() => { ... })처럼 의존성 배열 []을 아예 안 붙인 곳을 먼저 의심하세요. 배열이 없으면 매 렌더마다 실행되어 루프가 되기 쉽습니다.

---

A. 처음 한 번만 반짝인다: 하이드레이션 미스매치 / 테마 플래시

Next.js처럼 서버에서 미리 그린 화면(HTML)과 브라우저가 처음 그린 화면이 다르면, 그 순간 화면이 한 번 튑니다. 콘솔에 Text content did not match / Hydration failed가 뜹니다.

흔한 원인 (Next.js 공식 문서 기준)

  • window, localStorage, Date() 같은 걸 화면 그리는 코드에서 바로 사용
  • typeof window !== 'undefined' 같은 조건으로 서버와 화면을 다르게 그림
  • 다크/라이트 테마를 브라우저에서만 읽어 처음엔 반대로 보임
  • 브라우저 확장(번역기·다크모드 확장 등)이 HTML을 건드림 → 시크릿 창에서 테스트해 확인

해결 1: 브라우저에서만 필요한 부분은 useEffect로 미루기

서버/클라이언트가 처음엔 똑같이 그리고, 그 다음에 바꾸게 하는 방식입니다.

jsx

import { useState, useEffect } from 'react'

export default function App() {
  const [isClient, setIsClient] = useState(false)
  useEffect(() => { setIsClient(true) }, [])
  return <h1>{isClient ? '브라우저 전용 내용' : '미리 그린 내용'}</h1>
}

해결 2: 이 컴포넌트만 서버 렌더링 끄기 (지도·차트 등 브라우저 전용 위젯)

jsx

import dynamic from 'next/dynamic'
const NoSSR = dynamic(() => import('../components/no-ssr'), { ssr: false })

해결 3: 시계·날짜처럼 어쩔 수 없이 다른 값은 경고만 끄기

jsx

<time dateTime="2016-10-25" suppressHydrationWarning />

주의: 이건 한 단계만 적용되는 탈출구입니다. React가 불일치한 텍스트를 고쳐주지도 않으니 남용하지 마세요.

다크모드 깜빡임(흰 화면 → 어두워짐)이라면

next-themes를 쓰는 경우, 최상위 <html> 태그에 suppressHydrationWarning을 넣어야 하고, 테마 값을 읽어서 뭔가 그릴 땐 마운트된 뒤에 그려야 합니다.

jsx

// layout.jsx (app 디렉터리)
<html lang="ko" suppressHydrationWarning>

// 테마에 따라 다르게 그리는 컴포넌트
const [mounted, setMounted] = useState(false)
useEffect(() => { setMounted(true) }, [])
if (!mounted) return null

next-themes는 페이지가 뜨기 전에 실행되는 스크립트를 넣어 원래는 깜빡임이 없어야 정상입니다. 그래도 깜빡이면 위 두 가지(suppressHydrationWarning 누락, 마운트 전 렌더)가 빠졌을 확률이 큽니다.

---

AI에게 맡길 때 붙여넣을 만능 문장

화면이 [처음 한 번만 반짝 / 계속 깜빡]입니다. 개발자도구 Console에 나온 에러는 [에러 메시지 그대로 붙여넣기]입니다. 이 에러의 원인 컴포넌트를 찾아 공식 권장 방식으로 고쳐주세요. 임시로 감추지 말고 근본 원인을 잡아주세요.

확정 해결이 안 될 때 (지금 할 수 있는 것)

  • 브라우저 확장(번역·다크모드 확장 등)을 끄고 시크릿 창에서 재현되는지 확인 — 재현 안 되면 확장이 범인입니다.
  • Console 에러 전체를 복사해 AI에게 그대로 전달하세요. 에러 첫 줄이 보통 원인 파일과 줄 번호를 가리킵니다.