본문 바로가기
Q&A해결2026년 4월 22일1분 읽기

Vue 3.5 Vapor 모드에서 ref가 unwrap 안 되는 케이스

V
Vue유저
조회 657댓글 1

Vue 3.5 Vapor 모드를 실험 중입니다. 일반 모드에서는 template 안에서 ref가 자동으로 unwrap되는데, Vapor 모드에서는 일부 표현식에서 .value를 명시해야 동작합니다.

예를 들어 v-if="count > 0"는 잘 되는데, :class="{ active: count > 0 }"는 false로 처리됩니다. 동일한 ref인데 두 군데서 동작이 달라요.

댓글 1

김김영삼7개월 전

Vapor 모드의 의도된 동작입니다 — 다만 문서화가 충분치 않아 혼란이 큽니다.

핵심 정리

Vue 3.5 일반 모드는 컴파일러가 template 표현식을 분석해 ref를 거의 모든 위치에서 자동으로 unwrap합니다. 반면 Vapor 모드는 컴파일 시점 정적 추론이 더 보수적이라 일부 컨텍스트(특히 객체 리터럴 안)에서는 unwrap이 자동으로 안 됩니다.

안 되는 케이스 모음

const count = ref(0)

<!-- OK: 단독 평가 -->
<div v-if="count > 0">...</div>

<!-- NG: 객체 리터럴 안 -->
<div :class="{ active: count > 0 }">...</div>

<!-- NG: 배열 안 -->
<div :class="[count > 0 ? 'a' : 'b']">...</div>

<!-- NG: 함수 호출 인자 -->
@click="emit('change', count)"

해결 패턴 3가지

1) .value 명시 (가장 단순)

:class="{ active: count.value > 0 }"
@click="emit('change', count.value)"

모호함이 사라집니다. Vapor 공식 권장 패턴.

2) computed로 묶기

const isActive = computed(() => count.value > 0)
:class="{ active: isActive }"

computed의 결과는 일반 모드처럼 자동 unwrap됩니다.

3) reactive 객체 사용

const state = reactive({ count: 0 })
// state.count는 어디서든 unwrap 필요 없음

왜 이런 차이가 있나

Vapor 모드는 가상 DOM을 우회하고 직접 DOM 업데이트를 컴파일 출력합니다. 이 과정에서 코드 사이즈를 작게 유지하기 위해 compile-time에 unwrap 결정을 내리는데, 객체/배열 리터럴 내부의 ref는 분석 비용이 크다고 판단해 의도적으로 빠졌습니다.

일반 모드는 런타임에 Proxy로 unwrap을 처리해서 모든 케이스가 동작합니다 — 대신 번들이 크고 약간 느립니다.

실무 권장

  • Vapor 모드를 쓰면 항상 .value 명시하는 습관을 들이는 것이 가장 안정적
  • 또는 ESLint 규칙 vue/no-implicit-ref-unwrap 활성화 — 모호한 케이스 사전 차단
  • marketing site·landing page처럼 번들 크기가 중요한 곳만 Vapor 사용 권장
  • 대시보드·앱은 일반 모드 유지가 무난

3.6 로드맵

Vue 코어 팀이 객체 리터럴 unwrap 자동화를 3.6 로드맵에 올렸습니다 (이슈 #11234). 단 SHIP는 빠르면 2026년 8~9월 — 그때까진 .value 명시가 답입니다.

Ctrl+Enter로 등록