Vue2에서 Vue3로 전환할 때 반드시 알아야 할 마이그레이션 전략

1. 들어가며

Vue3는 Vue2와 비교해 많은 내부 구조와 API 방식이 변화되었습니다. 기존 Vue2 프로젝트를 Vue3로 마이그레이션하려면 단순한 버전 업그레이드를 넘어 구조적 변경이 필요합니다. 이 글에서는 Vue2에서 Vue3로 전환하고자 할 때 주의해야 할 핵심 포인트와 안전한 마이그레이션 절차를 소개합니다.

2. 마이그레이션의 핵심 변화 요약

항목	Vue2	Vue3
API 방식	Options API 중심	Composition API 도입
상태관리	Vuex	Pinia (권장)
라우터	Vue Router 3	Vue Router 4
반응형 시스템	Object.defineProperty 기반	Proxy 기반
템플릿 구조	루트 노드 1개 제한	Fragments 지원
라이프사이클 명칭	created, mounted 등	onMounted, onBeforeMount 등으로 변경 가능
Slots	기본 슬롯만 이름 지정 가능	v-slot과 명확한 구조 지원

3. 마이그레이션 전 준비사항

• vue@2에서 vue@3로 바로 업그레이드할 수 없습니다. 의존성 패키지(Vuetify, Vuex 등) 도 함께 버전을 맞춰야 합니다.
• vue-demi, @vue/composition-api를 통해 단계적 전환도 가능합니다.
• 아래 마이그레이션 빌드 도구 활용을 추천합니다.

npm install -g @vue/cli
vue upgrade --next

또는 공식 툴 사용

npx @vue/compat

4. 마이그레이션 빌드(Vue 2.7 + Vue 3 호환)

Vue 팀은 Vue2.7 (Naruto) 라는 특수 버전을 제공하여 일부 Vue3 기능(Composition API 등)을 Vue2 프로젝트에서 사용할 수 있도록 했습니다. 이 빌드를 활용하면 점진적으로 Vue3 문법으로 코드를 리팩토링할 수 있습니다.

5. 주요 변경 포인트 정리

1) v-model 변화

<!-- Vue2 -->
<input v-model="value" />

<!-- Vue3 -->
<input v-model="modelValue" @update:modelValue="..." />

 

2) this 사용 방식
Composition API에서는 this를 사용하지 않고, 함수 내에서 직접 선언된 변수/함수를 사용합니다.

// Vue2
this.message

// Vue3
const message = ref('Hello')

 

3) 라이프사이클 변화

// Vue2
mounted() { ... }

// Vue3
onMounted(() => { ... })

 

4) provide/inject 방식 변경

Vue3에서는 타입 지원 및 Composition API 기반으로 provide / inject를 설정합니다.

// provide
provide('message', ref('hello'))

// inject
const message = inject('message') as Ref<string>

6. 마이그레이션 단계별 절차

• 의존성 라이브러리 Vue3 지원 여부 확인
  > vuetify, vuex, vue-router, axios 등 사용 중인 라이브러리가 Vue3를 지원해야 합니다.
• Vue2.7 또는 마이그레이션 빌드 사용
  > 전체 전환이 어렵다면 Vue2.7을 사용해 일부 Composition API를 적용하며 점진적 전환 가능
• Composition API로 구조 전환
  > setup(), ref(), computed() 등으로 기존 Options API 코드를 리팩토링
• Vue Router 4 / Pinia 도입
  > Vue3 공식 권장 라이브러리로 전환
• 전역 설정 방식 변경 대응
  > 예: Vue.use() → app.use() 등

7. 마치며

Vue2에서 Vue3로의 전환은 단순한 문법 변경이 아닌, 아키텍처 수준의 전환입니다. 한 번에 모든 걸 바꾸려 하지 말고, 점진적이고 전략적인 접근이 중요합니다.

공식 문서: https://v3-migration.vuejs.org/

Vue 3 Migration Guide

실전 팁

• 소규모 컴포넌트부터 Vue3 문법으로 전환해보세요.
• Composition API 문법에 익숙해지면 전체 프로젝트 전환이 훨씬 쉬워집니다.
• 호환 모드(Migration build)는 장기 사용보다는 과도기적 도구로만 활용하세요.