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. 마이그레이션 가이드 구조
공식 가이드를 큰 덩어리로 나누면 보통 이런 식으로 구성됩니다.
- 개요 및 마이그레이션 전략
- Vue 2와 Vue 3의 관계
- 점진적인 업그레이드(Compat build 활용) 전략
- 무엇부터 손대야 하는지에 대한 제안
- 브레이킹 체인지(중요 변경점) 목록
- Global API 변경 (Vue.use, Vue.component 등)
- 템플릿 / 디렉티브 변경 (v-model, filter 제거 등)
- 컴포넌트 옵션 및 인스턴스 API 변경
- 렌더링 / 슬롯 관련 변경
- Transition, 이벤트 등 기타 변경
- Deprecated / 제거된 기능들
- 템플릿 필터
- 일부 인스턴스 메서드 / 옵션
- 사용은 가능하지만 더 이상 권장되지 않는 패턴들
- 도구 / 생태계 관련
- Vue CLI → Vite (권장)
- Vuex → Pinia 권장 분위기
- Router 3 → Router 4 마이그레이션 가이드
- 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를 쓸 경우 콘솔에 경고를 띄워서 수정이 필요한 부분을 알려줍니다.
실무에서 대규모 프로젝트를 마이그레이션 해야 할 때는 아래와 같은 전략을 공식적으로 제안하고 있습니다.
- 먼저 Vue 2 → Vue 3 + Compat Build로 올리고
- 콘솔 경고를 하나씩 해결해 가면서
- 최종적으로 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에 자주 등장하는 변경항목을 실무 체크리스트 형식으로 재구성한 것입니다.
정리
- 공식 마이그레이션 가이드는 목차가 곧 로드맵
- 개요 / 전략 → 브레이킹 체인지 → Deprecated → Compat build
- 특히 중점적으로 보게 될 카테고리
- Global API 변경 (Vue.use → app.use)
- 템플릿 / 디렉티브 (v-model, 필터 제거)
- 컴포넌트 옵션 / 인스턴스 API (라이프사이클, $on 등)
- Compat Build는 올인원 리팩토링 방지 장치
- Vue 3에서 Vue 2 스타일 코드가 돌아가게 해주고
- 콘솔 경고를 통해 하나씩 수정할 수 있게 도와줌
이 글에서는 전체적으로 본 느낌이고, 다음 글부터는 구체적인 변경점들을 하나씩 짚어볼 예정입니다.
출처
Vue 공식 문서 - Vue 3 Migration Guide
'Framework > Vue' 카테고리의 다른 글
| Vue 3에서 달라진 v-model과 템플릿 필터 제거 정리 (0) | 2025.11.28 |
|---|---|
| Vue 2의 Vue.use에서 Vue 3 Global API, createApp로 마이그레이션 (0) | 2025.11.27 |
| Vue 3 생태계 한 눈에 정리 (0) | 2025.11.27 |
| Vue 3 + Router 4 + Pinia로 미니 SPA 만들기 (0) | 2025.11.26 |
| Vue3 <script setup> 정리: defineProps, defineEmits, defineExpose (0) | 2025.11.26 |