[Vue.js] 환경 변수 관리(.env): `--mode` 옵션으로 깔끔하게 해결하는 법

---

Vue.js 환경 변수 관리(.env): --mode 옵션으로 깔끔하게 해결하는 법

Vue.js 프로젝트에서 개발, 테스트, 배포 등 다양한 환경에 따라 API 엔드포인트나 기타 설정 값을 다르게 지정하는 것은 개발 과정에서 필수적이다. 이 환경 변수를 효율적으로 관리하기 위해 Vue CLI는 강력한 --mode 옵션을 제공하고 있다. 이 글에서는 기존에 발생했던 cross-env 사용 시의 문제점을 짚어보고, --mode 옵션을 활용하여 환경 변수를 정확하게 매핑하는 방법을 소개한다.

---

1. cross-env 사용 시 발생했던 문제점

이전에 package.json 스크립트에서 cross-env를 사용하여 VUE_APP_ENV와 같은 환경 변수를 주입하는 방식이 흔하게 사용되었다. 예를 들어, 다음과 같은 설정이다.

"scripts": {
  "serve:dev": "cross-env VUE_APP_ENV=dev vue-cli-service serve"
}

이 방식은 VUE_APP_ENV 변수를 dev로 설정하는 데는 성공적이었다. 실제로 process.env.VUE_APP_ENV를 출력하면 dev가 나오는 것을 확인할 수 있었다. 하지만 문제는 Vue CLI가 이 변수 값만으로 원하는 .env.dev 파일을 정확히 로드하지 못하는 경우가 발생했다는 것이다.

Vue CLI는 serve 명령어를 실행할 때 기본적으로 development 모드로 작동하며, 이때 .env.development.local 또는 .env.local 같은 파일을 더 높은 우선순위로 로드한다. 따라서 cross-env로 VUE_APP_ENV=dev를 설정했더라도, 만약 우선순위가 더 높은 .env 파일에 동일한 이름의 환경 변수(VUE_APP_API_URL 등)가 정의되어 있었다면, 그 값이 .env.dev 파일의 값을 덮어썼던 것이다. 이것이 바로 VUE_APP_ENV는 dev로 나오는데 VUE_APP_API_URL은 다른 값을 가리키는 원인이었다.

---

2. --mode 옵션으로 명확하게 해결

Vue CLI의 --mode 옵션은 이러한 혼란을 깔끔하게 해결해 주는 핵심 기능이다. 이 옵션은 Vue CLI에게 어떤 "모드"로 빌드 또는 개발 서버를 실행할지 명확하게 지시하는 역할을 한다. --mode 옵션을 사용하면 Vue CLI는 해당 모드 이름과 일치하는 .env.[mode] 파일을 최우선적으로 찾아 로드하게 된다.

2.1. package.json 스크립트 수정 방법

이제 package.json의 scripts 부분을 다음과 같이 수정하면 된다. cross-env는 더 이상 필요하지 않다.

{
  "scripts": {
    "serve": "vue-cli-service serve",
    "build": "vue-cli-service build",
    "lint": "vue-cli-service lint",
    "serve:local": "vue-cli-service serve --mode local",
    "serve:dev": "vue-cli-service serve --mode dev",
    "build:local": "vue-cli-service build --mode local",
    "build:dev": "vue-cli-service build --mode dev"
  }
}

• cross-env VUE_APP_ENV=... 제거: 환경 변수를 설정하는 부분이 사라진 것이 특징이다. Vue CLI가 --mode 옵션에 따라 .env 파일을 자동으로 로드하고 변수를 주입하기 때문이다.
• --mode [모드명] 추가: vue-cli-service serve 또는 vue-cli-service build 명령어 뒤에 --mode local 또는 --mode dev를 직접 추가하여 어떤 환경 변수 파일(예: .env.local, .env.dev)을 사용할지 명시한다.

2.2. 사용 예시

이제 각 환경에 맞는 스크립트를 다음과 같이 실행할 수 있다.

• 로컬 환경에서 개발 서버 실행:

  npm run serve:local
  # 또는
  yarn serve:local

• 개발 서버용 빌드 실행:

  npm run build:dev
  # 또는
  yarn build:dev

---

3. --mode 사용의 이점

--mode 옵션을 사용하는 것이 더 좋은 이유는 명확하다.

• 정확한 환경 변수 로드: Vue CLI가 명시된 모드에 해당하는 .env 파일을 최우선으로 로드하므로, 의도한 환경 변수 값이 정확하게 적용된다.
• 간결하고 명확한 스크립트: cross-env와 같은 추가적인 유틸리티 없이 스크립트 자체가 간결해지고, 어떤 환경 파일이 사용되는지 쉽게 파악할 수 있다.
• 예측 가능한 동작: Vue CLI의 공식적인 환경 변수 로드 메커니즘을 따르므로, .env.local이나 .env.development 같은 다른 파일과의 우선순위 충돌 없이 예측 가능한 결과를 얻을 수 있다.

이러한 --mode 옵션 활용법을 통해 Vue.js 프로젝트의 환경 변수 관리를 더욱 효율적이고 안정적으로 수행할 수 있을 것이다.

---