Xcode에서 환경변수 관리하기

xcode를 활용한 iOS 프로젝트를 개발해보면서 환경변수를 관리하는 방법에 기록하고자 한다.

기존에 React, Nest.js, FastAPI를 사용할 때는 .env 파일을 사용하여 환경변수를 관리했지만, xcode를 활용한 iOS 프로젝트를 개발할 때는 어떻게 환경변수를 관리할 수 있을까 하는 생각이 있었다.

github에 API Key를 올리지 않고 프로젝트 관리를 하는 것은 필수적이기에 환경변수 사용을 찾아 보았다.

당연하게도 apple에서는 이미 만들어뒀다. xcconfig-사용법-공식페이지

그렇지만, 아마 누군가에게 도움이 되고자 나는 이미지를 조합해서 작성했다.

Configuration 파일 만들기

가장 먼저 환경변수 파일을 만든다.

Xcode에서 cmd + n (New File)을 누른다.
Configuration Settings File을 검색해서 선택한다.
환경별로 파일을 만든다:

Debug.xcconfig (개발용)
Release.xcconfig (배포용)

변수 정의하기

// // 슬래시 두 개는 주석으로 인식되므로 URL 입력 시 주의해야 합니다.
// 팁: https:/$()/ 처럼 중간에 빈 괄호를 넣으면 주석 처리를 피할 수 있습니다.
BASE_URL = https:/$()/dev-api.tyquill.com
API_KEY = dev_12345_key
APP_NAME = Doremi

APP_NAME = "Doremi" -> ❌, xcconfig 에서는 ""도 문자열로 인식한다
APP_NAME = Doremi -> ✅

프로젝트에 연결하기

파일만 만들어서는 Xcode가 인식을 못 한다. 프로젝트 설정에서 연결해줘야 한다.

좌측 네비게이터에서 최상단 프로젝트(파란 아이콘) 클릭.
PROJECT (Targets 아님) 선택 -> Info 탭 클릭.
Configurations 섹션 확인.
Debug 항목을 펼쳐서 None을 방금 만든 Debug 파일로 변경.
Release 항목을 펼쳐서 None을 방금 만든 Release 파일로 변경.

Info.plist에 변수 등록하기

.xcconfig에 적은 값은 ‘빌드 세팅’에는 들어갔지만, 아직 스위프트 코드에서는 못 읽어서 Info.plist

Info.plist 파일을 연다. (또는 Target > Info 탭)
새로운 Key를 추가한다 (예: BaseURL, ApiKey).
Value 부분에 $(변수명) 형태로 입력한다.
- Key: BaseURL, Value: $(BASE_URL)
- Key: ApiKey, Value: $(API_KEY)

주의: 여기서 $(BASE_URL)은 xcconfig 파일에 적은 변수명과 똑같아야 한다

아래 이미지는 Amplitude API Key를 등록한 모습이다.

Swift 코드에서 사용하기

이제 Bundle을 통해 값을 가져올 수 있다. 매번 코드를 치기 귀찮으니 깔끔하게 Helper 구조체를 만들어 쓰는 것을 추천한다!

import Foundation

struct Config {
    // Info.plist에서 값을 읽어오는 헬퍼 메서드
    private static func infoDictionaryValue(for key: String) -> String {
        guard let value = Bundle.main.infoDictionary?[key] as? String else {
            fatalError("Info.plist에 '\(key)' 키가 누락되었습니다.")
        }
        return value
    }

    // 코드에서 사용할 변수들
    static var baseURL: String {
        return infoDictionaryValue(for: "BaseURL")
    }

    static var apiKey: String {
        return infoDictionaryValue(for: "ApiKey")
    }
}

// 사용 예시
let url = URL(string: Config.baseURL)
print("현재 API 키: \(Config.apiKey)")

보안

당연하게도 API Key 같은 민감한 정보가 있다면, .xcconfig 파일은 깃허브에 올리지 않고 .gitignore에 추가하는 것이 좋다.

팀원들과 공유할 때는 Debug.xcconfig.template 같은 파일을 만들어서 키 값만 비워두고 공유한다