Vue 2에서 Vue 3로: 공식 마이그레이션 가이드 구조 한 눈에 정리

1. 서론

이전까지는 Vue 3 생태계를 익혔다면, 이제부터는 Vue 2에서 Vue 3 마이그레이션을 보도록 하겠습니다.

먼저 공식 마이그레이션 가이드가 어떻게 구성되어있는지를 구조적으로 읽어보겠습니다.

Vue에서 어떤 부분이 깨지는지, 어떤 기능이 deprecated인지,

어떤 순서로 점진적으로 올리는 게 좋은지 정리해둔 문서를 제공하고 있습니다.

이걸 목차 중심으로 한 번 훑어보고 나서 체크리스트를 만들어보겠습니다.

 

---

 

2. 공식 마이그레이션 가이드는 어디에 있을까?

Vue 3와 Vue 2는 API 구조가 완전히 다른 게 아니라, 상당 부분은 호환되지만 일부가 깨지는 메이저 버전에 가깝습니다.

그래서 Vue에서 전용 Migration Guide를 제공하고 있습니다.

Vue 2에서 3로 갈 때 breaking changes를 한 곳에 모아두었고,

변경 내용마다 Vue 2에서의 사용 예, Vue 3에서의 대처 방법,

Compat build 사용 시 경고 메시지 등을 예제로 보여줍니다.

단순 API 나열이 아니라, 점진적 마이그레이션 전략에 대한 설명도 포함되어 있습니다.

 

오늘은 이 문서 전체를 다 해석하기보다,

어떤 카테고리로 나뉘어 있고, 어디를 집중해서 봐야 하는지를 정리하는 데 집중합니다.

 

---

 

3. 마이그레이션 가이드 구조

공식 가이드를 큰 덩어리로 나누면 보통 이런 식으로 구성됩니다.

1. 개요 및 마이그레이션 전략
   • Vue 2와 Vue 3의 관계
   • 점진적인 업그레이드(Compat build 활용) 전략
   • 무엇부터 손대야 하는지에 대한 제안
2. 브레이킹 체인지(중요 변경점) 목록
   • Global API 변경 (Vue.use, Vue.component 등)
   • 템플릿 / 디렉티브 변경 (v-model, filter 제거 등)
   • 컴포넌트 옵션 및 인스턴스 API 변경
   • 렌더링 / 슬롯 관련 변경
   • Transition, 이벤트 등 기타 변경
3. Deprecated / 제거된 기능들
   • 템플릿 필터
   • 일부 인스턴스 메서드 / 옵션
   • 사용은 가능하지만 더 이상 권장되지 않는 패턴들
4. 도구 / 생태계 관련
   • Vue CLI → Vite (권장)
   • Vuex → Pinia 권장 분위기
   • Router 3 → Router 4 마이그레이션 가이드
5. Compat build (Vue 2 스타일 코드를 Vue 3에서 돌려보기)
   • Compat 모드 개념
   • 경고 메시지를 통해 문제 지점 찾는 방법
   • Compat에서 pure Vue 3 코드로 옮겨가는 전략

앞으로 이 카테고리들을 하나씩 파고들면서 체크리스트를 만들어보겠습니다.

 

---

 

4. 핵심 변경 카테고리

1️⃣ Global API 변경

Vue 2에서는 아래처럼 전역 Vue 객체에 플러그인을 등록했습니다.

import Vue from 'vue'
import Router from 'vue-router'

Vue.use(Router)

Vue 3에서는 createApp으로 앱 인스턴스를 만든 뒤,

그 인스턴스에 대해 app.use()를 호출하는 방식으로 바뀌었습니다.

import { createApp } from 'vue'
import router from './router'

const app = createApp(App)
app.use(router)
app.mount('#app')

마이그레이션 가이드에서도 가장 먼저 언급되는 변경 중 하나입니다.

 

---

 

2️⃣ 템플릿 / 디렉티브 변경

마이그레이션 가이드에서 굉장히 강조하는 부분이 v-model과 필터(filter)입니다.

Vue 2의 v-model은 기본적으로 value prop + input 이벤트에 바인딩되는 패턴이었고,

Vue 3에서는 표준화된 인터페이스인 modelValue + update:modelValue 패턴으로 바뀌었습니다.

 

<template>
  <CustomInput v-model="searchText" />
</template>

부모컴포넌트가 위와 같을 때, 자식 컴포넌트는 각각 아래와 같습니다.

 

[Vue 2]

<template>
  <input :value="value" @input="$emit('input', $event.target.value)" />
</template>

<script>
export default {
  props: ['value']
};
</script>

 

[Vue 3]

<template>
  <input :value="modelValue" @input="$emit('update:modelValue', $event.target.value)" />
</template>

<script setup>
defineProps(['modelValue']);
defineEmits(['update:modelValue']);
</script>

 

---

 

또한 템플릿 필터 ({{ value | capitalize }})는 Vue 3에서 완전히 제거되며,

대신 computed나 methods로 처리하라고 명시되어 있었습니다.

→ 프로젝트에 | 필터 문법이 많이 쓰인다면, 이 부분을 반드시 체크해야 합니다.

 

[Vue 2 (Options API)]

<template>
  <p>{{ message | capitalize }}</p>
</template>

<script>
export default {
  data() {
    return {
      message: 'hello world'
    };
  },
  filters: {
    capitalize(value) {
      if (!value) return '';
      value = value.toString();
      return value.charAt(0).toUpperCase() + value.slice(1);
    }
  }
};
</script>

 

[Vue 3 + Composition API]

<template>
  <p>{{ capitalizedMessage }}</p>
</template>

<script setup>
import { ref, computed } from 'vue';

const message = ref('hello world');

const capitalizedMessage = computed(() => {
  const value = message.value;
  if (!value) return '';
  return value.charAt(0).toUpperCase() + value.slice(1);
});
</script>

 

[Vue 3 + Options API]

<template>
  <p>{{ capitalizedMessage }}</p>
</template>

<script>
export default {
  data() {
    return {
      message: 'hello world'
    };
  },
  computed: {
    capitalizedMessage() {
      const value = this.message;
      if (!value) return '';
      return value.charAt(0).toUpperCase() + value.slice(1);
    }
  }
};
</script>

 

---

 

3️⃣ 컴포넌트 / 인스턴스 옵션 변경

• 라이프사이클 훅 이름 일부 변경
  • destroyed → unmounted
  • beforeDestory → beforeUnmount 등
• $on, $off, $once 같은 인스턴스 이벤트 API 제거
  • event bus 패턴을 쓰는 레거시 코드에서 이 부분이 자주 문제

 

---

 

5. Compat Build란 무엇이고 언제 쓸까?

Vue 3 마이그레이션 문서를 보면 Compat build(호환 빌드) 섹션이 따로 있습니다.

Vue 3를 사용하지만, Vue 2 API 대부분을 그대로 쓸 수 있는 모드입니다.

Vue 3 프로젝트에 compat build를 적용하면 Vue 2 스타일 코드가 어느 정도 그대로 동작합니다.

대신, Vue 3에서 deprecated / 변경된 API를 쓸 경우 콘솔에 경고를 띄워서 수정이 필요한 부분을 알려줍니다.

 

실무에서 대규모 프로젝트를 마이그레이션 해야 할 때는 아래와 같은 전략을 공식적으로 제안하고 있습니다.

1. 먼저 Vue 2 → Vue 3 + Compat Build로 올리고
2. 콘솔 경고를 하나씩 해결해 가면서
3. 최종적으로 pure Vue 3 빌드로 전환

이 부분은 나중에 다시 자세히 볼 예정입니다.

 

---

 

6. 프로젝트 마이그레이션 목차 만들기

[프로젝트 Vue 2 + Vue 3 마이그레이션 체크리스트]

1. Global API
	- [ ] Vue.use(...) 사용하는 곳 목록
    - [ ] Vue.mixin, Vue.component 등 전역 등록 부분

2. 템플릿 / 디렉티브
	- [ ] v-model 커스텀 컴포넌트 사용 부분
    - [ ] 템플릿 필터 ({{ value | something }})
    - [ ] keyCode 기반 이벤트 사용하는 부분

3. 컴포넌트 옵션 / 인스턴스
	- [ ] destroyed / beforeDestroy 사용 부분
    - [ ] this.$on / this.$off / this.$once 사용 부분
    - [ ] mixins로 재사용하는 로직

4. 라우터 / 상태 관리
	- [ ] vue-router@3 사용 여부 및 설정 구조
    - [ ] Vuex Store 구조 (modules, plugins)

5. 빌드 / 도구
	- [ ] Vue CLI → Vite 전환 여부
    - [ ] Babel / TypeScript 설정 점검

이 틀은 Vue 3 Migration Guide에 자주 등장하는 변경항목을 실무 체크리스트 형식으로 재구성한 것입니다.

 

---

 

정리

1. 공식 마이그레이션 가이드는 목차가 곧 로드맵
   • 개요 / 전략 → 브레이킹 체인지 → Deprecated → Compat build
2. 특히 중점적으로 보게 될 카테고리
   • Global API 변경 (Vue.use → app.use)
   • 템플릿 / 디렉티브 (v-model, 필터 제거)
   • 컴포넌트 옵션 / 인스턴스 API (라이프사이클, $on 등)
3. Compat Build는 올인원 리팩토링 방지 장치
   • Vue 3에서 Vue 2 스타일 코드가 돌아가게 해주고
   • 콘솔 경고를 통해 하나씩 수정할 수 있게 도와줌

이 글에서는 전체적으로 본 느낌이고, 다음 글부터는 구체적인 변경점들을 하나씩 짚어볼 예정입니다.

 

---

 

출처

Vue 공식 문서 - Vue 3 Migration Guide