xcconfig 다중 환경 설정: 2026 원격 iOS 빌드 튜토리얼

📋 목차

로컬 Release는 정상인데 원격 Archive가 테스트 주소를 사용한다면, 공개 설정은 xcconfig로 분리하고 비밀값은 원격 환경에서 주입한 뒤 최종 Archive를 검사해야 합니다. 개발·테스트·출시 환경을 서로 다른 Target으로 복제하지 말고, 공통 기준과 명확한 Scheme 매핑부터 고정하십시오.

이 글은 개발·테스트·출시 API를 함께 관리하면서 Xcode Build Settings의 수동 차이를 줄이려는 독립 개발자를 위한 글입니다. 프로젝트를 원격 Mac으로 옮기거나, 스크립트와 CI에서 반복적으로 iOS Archive를 만들려는 소규모 팀에도 적용할 수 있습니다.

실패 원인은 설정 파일이 아니라 최종 계산값에 있습니다

대표적인 실패는 다음과 같습니다. 로컬에서 Release 빌드는 출시 서버를 사용합니다. 그러나 원격 Mac에서 만든 Archive는 테스트 서버를 가리킵니다. 저장소 안에 올바른 xcconfig 파일이 있어도 이 문제는 발생할 수 있습니다.

먼저 역할을 분리해야 합니다.

Scheme: 어떤 작업 흐름과 Build Configuration을 선택할지 결정합니다.
Build Configuration: Debug, 테스트, Release 같은 빌드 변형을 구분합니다.
Target: 앱, Widget, Notification Service처럼 실제로 빌드되는 대상을 구분합니다.
xcconfig: Xcode Build Settings를 텍스트로 공유하고 조합합니다.
Info.plist: 빌드 시 치환된 값을 앱 번들에 전달합니다.
실행 시 설정: 앱이 실행된 뒤 읽는 값입니다.
서명 자산과 비밀값: 인증서, 개인 키, API Key처럼 별도 보호가 필요한 입력입니다.

Apple은 Build Configuration 파일을 프로젝트에 추가하는 방법과 xcconfig의 용도를 설명합니다. 따라서 xcconfig를 비밀 저장소나 실행 시 환경 전환 기능으로 설명하면 안 됩니다.

설정은 세 층으로 나누십시오.

모든 환경이 공유하는 컴파일 기준과 공통 경로
개발·테스트·출시마다 달라지는 서버 주소와 기능 플래그
저장소에 넣지 않는 API Key, 서명 자격 정보, 업로드 인증 정보

이 구조를 사용하면 공개 설정은 코드 리뷰와 버전 관리의 대상이 됩니다. 반면 비밀값은 원격 Mac에서 주입됩니다. 중요한 것은 파일 내용이 아니라 Xcode가 계산한 최종 값입니다. Apple의 Build Settings Reference를 기준으로 프로젝트, 설정 파일, Target, 명령줄 입력이 어떻게 결과를 바꾸는지 확인하십시오.

단일 앱은 복제보다 공통 기준과 차이값으로 관리합니다

Debug와 Release만 있는 작은 앱이라면 모든 Xcode 기본값을 xcconfig로 복사하지 마십시오. 기본값까지 복사하면 Xcode 버전이나 프로젝트 형식이 바뀔 때 오래된 값이 조용히 남을 수 있습니다.

저장소에 포함하기 좋은 값은 다음과 같습니다.

앱의 비민감한 식별자
공통 Swift 컴파일 설정
공개 가능한 개발·테스트·출시 서버 주소
기능 플래그와 로그 수준
환경별 Bundle ID처럼 검토 가능한 빌드 차이

반대로 다음 값은 외부 입력으로 남겨야 합니다.

API Key와 장기 토큰
인증서 비밀번호
서명용 개인 키의 보호 정보
App Store 업로드 자격 정보
개인 컴퓨터의 절대 경로

여기서 서버 주소와 API Key를 같은 방식으로 다루면 안 됩니다. 주소는 공개 저장소에 들어갈 수 있지만, 키는 xcconfig에 적는 순간 저장소 기록과 빌드 로그에 남을 위험이 생깁니다. xcconfig는 값을 조합하는 형식이지 암호화 기능이 아닙니다.

로컬 검증은 두 갈래로 진행하십시오.

Build: 개발 Scheme이 개발 주소와 개발 Bundle ID를 사용하는지 확인합니다.
Archive: 출시 Scheme이 출시 주소와 출시 Bundle ID를 사용하는지 확인합니다.

Build만 성공했다고 Archive도 올바른 것은 아닙니다. Archive는 별도의 Scheme 동작과 서명 입력을 거칩니다. Apple의 App Archive 생성 안내처럼 출시 산출물을 기준으로 확인해야 합니다.

환경이 늘어날수록 Scheme 매핑을 먼저 고정합니다

개발, 테스트, 출시 환경을 구분할 때 가장 먼저 할 일은 이름을 정하는 것이 아니라 연결 관계를 문서화하는 것입니다.

개발 Scheme → 개발 Build Configuration → 개발 API 주소
테스트 Scheme → 테스트 Build Configuration → 테스트 API 주소
출시 Scheme → Release Build Configuration → 출시 API 주소

이 매핑이 불명확하면 같은 이름의 설정이 다른 파일에서 덮어써질 수 있습니다. 특히 API_URL, PRODUCT_BUNDLE_IDENTIFIER, SWIFT_ACTIVE_COMPILATION_CONDITIONS처럼 여러 계층에서 자주 쓰는 값은 최종 결과를 반드시 확인하십시오.

Scheme의 실행, 테스트, Archive 동작은 서로 다를 수 있습니다. 프로젝트 Build Scheme 사용자화 안내를 참고해 Archive 단계가 어떤 Configuration을 선택하는지 확인하십시오.

다음 조건 중 하나라도 만족하면 출시 Archive를 멈추십시오.

최종 서버 주소에 테스트 문자열이 남아 있습니다.
출시 Bundle ID가 아닌 값이 계산됩니다.
출시 Target의 Entitlements가 비어 있거나 예상과 다릅니다.
테스트용 기능 플래그가 활성화되어 있습니다.
원격 환경에서 필요한 공개 xcconfig가 복원되지 않았습니다.

이 중 하나라도 발견되면 수동으로 주소를 바꿔 다시 빌드하지 마십시오. Scheme, Configuration, 설정 파일 연결 중 어느 계층이 잘못되었는지 먼저 수정해야 합니다.

여러 Target은 공유 범위와 전용 범위를 나눕니다

Widget, Notification Service, Share Extension이 포함된 앱에서는 메인 앱이 성공한 것만으로 충분하지 않습니다. 각 Target은 별도의 Bundle ID와 Entitlements를 가질 수 있고, App Group이나 배포 대상도 달라질 수 있습니다.

공유해도 되는 설정은 프로젝트 수준에 둡니다.

공통 Swift 컴파일 기준
공통 경고 정책
공통 배포 대상
공개 가능한 환경 이름

Target 전용으로 남겨야 하는 설정은 각 Target에서 확인합니다.

Bundle ID
Entitlements
App Group
확장 전용 Info.plist 값
Target별 링크 프레임워크와 리소스

Apple의 여러 Target을 빌드하는 Xcode 안내처럼 Target은 단순한 환경 이름이 아니라 함께 배포되는 실제 빌드 단위입니다. 환경이 다르다는 이유만으로 앱 Target을 복제하면 설정 차이가 늘고, 어느 Target이 출시 대상인지 확인하기 어려워집니다.

프로젝트 구조에 따른 선택 기준을 먼저 적용합니다

다음 조건 목록을 Archive 전에 실행하면, 환경 차이 때문에 Target을 불필요하게 복제하는 일을 줄일 수 있습니다.

[ ] 개발·테스트·출시의 차이가 서버 주소와 기능 플래그뿐이면 공통 Target과 여러 Build Configuration을 선택합니다.
[ ] Widget이나 확장처럼 별도 번들이 필요하면 Target 전용 설정을 추가합니다.
[ ] 각 환경의 Scheme이 정확한 Build Configuration과 연결되어 있으면 다음 단계로 이동합니다.
[ ] API Key, 장기 토큰, 인증서 비밀번호가 저장소와 xcconfig에 없으면 외부 주입 방식을 사용합니다.
[ ] 원격 Mac에서 깨끗한 저장소 검출 후 공개 xcconfig가 복원되면 비대화형 Build를 진행합니다.
[ ] 최종 계산값과 Archive 안의 서버 주소가 출시 값이면 업로드 검수를 진행합니다.
[ ] 하나라도 확인하지 못했거나 테스트 값이 남아 있으면 Archive 업로드를 중단하고 설정 계층을 수정합니다.

판단을 더 단순하게 만들면 다음과 같습니다.

환경 주소만 다르면 Build Configuration을 선택합니다.
앱과 확장의 번들 구조가 다르면 Target 전용 설정을 선택합니다.
설정 파일이 환경마다 중복되면 공통 기준을 먼저 추출합니다.
비밀값을 파일에 넣어야만 빌드된다면 외부 주입 절차를 다시 설계합니다.
Archive 결과를 자동으로 확인할 수 없다면 출시 전에 검수 단계를 추가합니다.

이 목록은 설치 순서가 아니라 선택 기준입니다. 프로젝트가 커질수록 모든 설정을 한 파일에 모으는 것보다, 어떤 값이 어느 계층에 속하는지 설명할 수 있는지가 중요합니다.

원격 Mac에서는 복원 가능성과 비밀 주입을 따로 검증합니다

원격 Mac에서 xcconfig가 적용되지 않는 문제는 대개 설정 자체보다 환경 복원 과정에서 발생합니다. 저장소에는 파일이 있지만 프로젝트 파일이 그 파일을 참조하지 않거나, 원격 Scheme이 커밋되지 않았거나, 원격 작업 디렉터리가 다른 경로일 수 있습니다.

다음 순서로 확인하십시오.

깨끗한 작업 디렉터리에 저장소를 다시 받습니다.
프로젝트 파일과 공개 xcconfig 연결 정보가 함께 복원되는지 확인합니다.
사용할 Scheme과 Build Configuration을 명시합니다.
비밀값이 필요한 파일이나 환경 입력을 원격 실행 전에 제한된 방식으로 주입합니다.
비대화형 Build를 실행하고 최종 계산값을 기록합니다.
Release Archive를 만든 뒤 번들 내부의 환경값과 권한을 검사합니다.
원격 Mac을 재시작한 뒤 같은 과정을 반복해 우연한 세션 상태를 제거합니다.

비밀값을 주입하는 방식은 팀의 운영 환경에 맞춰 선택하되, xcconfig에 장기 토큰을 직접 커밋하지 마십시오. 로그에 명령줄 인자가 그대로 남는 방식도 피해야 합니다. 서명 자산은 별도로 보관하고, 필요한 경우 App Store Provisioning Profile 생성 안내를 기준으로 유효한 자산인지 확인하십시오.

원격 Mac을 새로 준비해야 한다면 원격 Mac의 iOS 빌드 환경 초기화와 검수에 정리된 환경 점검 항목을 함께 확인할 수 있습니다. 기존 장비에서 서명 자산을 옮기는 경우에는 iOS 빌드 머신 이전과 서명 자산 백업처럼 자산 복원과 실제 Archive 검증을 분리해서 진행해야 합니다.

독립 FAQ: 환경 분리와 원격 Archive 검수

xcconfig에서 개발, 테스트, 출시 환경을 어떻게 나누나요?

공통 설정을 공유 기준으로 두고 개발·테스트·출시 차이만 별도 파일에 둡니다. 각 파일은 Build Configuration과 Scheme에 명확히 연결해야 합니다. 서버 주소나 기능 플래그처럼 공개해도 되는 값은 저장소에 포함할 수 있지만, 비밀 키와 서명 정보는 저장소 밖에서 주입해야 합니다.

로컬에서는 적용되는데 원격 Mac에서는 왜 적용되지 않나요?

원격 저장소에 설정 파일이 빠졌거나 프로젝트 파일의 연결 정보가 커밋되지 않았을 가능성이 큽니다. 원격 Scheme이 다른 Build Configuration을 선택했거나 명령줄 인자가 값을 덮어쓸 수도 있습니다. 파일 존재보다 최종 계산된 Build Settings와 Archive 결과를 확인해야 합니다.

API Key와 서버 주소를 함께 xcconfig에 저장해도 되나요?

서버 주소는 공개 가능한 값이라면 저장할 수 있지만 API Key는 같은 방식으로 관리하면 안 됩니다. 키와 서명 자격 정보는 제한된 원격 파일이나 비밀 관리 기능에서 주입하십시오. 빌드 로그와 저장소 기록에 키가 남지 않는지도 함께 확인해야 합니다.

여러 Target과 Build Configuration은 어떻게 선택하나요?

환경 차이만으로 Target을 복제하지 말고 Build Configuration과 Scheme을 먼저 사용합니다. Widget이나 확장처럼 별도 번들이 필요한 경우에만 Target 전용 설정을 둡니다. 각 Target의 Bundle ID, Entitlements, App Group과 배포 대상은 최종 빌드값으로 따로 검증해야 합니다.

Archive가 올바른 xcconfig를 사용했는지 어떻게 확인하나요?

Archive 직전에 Scheme과 Configuration을 확인하고 Xcode의 최종 계산값을 검토하십시오. Archive 뒤에는 Bundle ID, 서버 환경, Entitlements와 필요한 기호 파일을 확인해야 합니다. 테스트 주소나 비생산용 값이 발견되면 업로드를 중단하는 조건을 자동화하는 편이 안전합니다.

출시 담당자는 프로젝트가 아니라 최종 산출물을 승인해야 합니다

출시 전 검수는 다음 순서로 고정하십시오.

Archive에 사용된 실제 Configuration 확인
최종 Bundle ID 확인
앱에 포함된 서버 환경 확인
모든 동봉 Target의 Entitlements 확인
필요한 기호 파일과 보관 파일 존재 확인
테스트 주소와 비생산용 플래그 검색
비정상 값 발견 시 업로드 중단

Archive 검증은 Apple의 App Archive 검증 안내를 기준으로 진행할 수 있습니다. 서명 자산 자체의 존재만 확인하지 말고, 실제 출시 산출물이 기대한 앱 권한과 식별자를 갖는지 확인해야 합니다.

현재 컴퓨터에서만 성공하고 원격 Mac에서는 실패한다면 결론은 세 가지 중 하나입니다. 공개 설정 계층을 수정하거나, 비밀 주입 절차를 다시 만들거나, 깨끗한 저장소 검출과 Archive가 반복되는 원격 빌드 환경을 준비해야 합니다. 어느 경우든 수동으로 Scheme을 바꾸는 절차를 장기 운영 규칙으로 남겨서는 안 됩니다.

매번 원격 환경을 새로 준비하거나 기존 컴퓨터를 계속 켜 두는 방식은 절대 경로, 로그인 세션, 로컬에만 남은 파일에 의존하기 쉽습니다. 특히 자체 장비는 전원과 재시작, 저장 공간, 서명 자산 백업을 직접 관리해야 합니다. 반대로 MacDate의 원격 Mac은 이런 환경을 단기 검증이나 반복 Archive에 활용하려는 경우에 선택지가 될 수 있습니다. 다만 물리 장비에 직접 접근해야 하거나 장기간 고정 부하를 계속 처리해야 한다면 직접 구매가 더 적합할 수 있습니다.

먼저 깨끗한 환경에서 저장소 검출과 Release Archive를 한 번 완주하십시오. 그 과정에서 원격 Mac의 전달 방식과 빌드 환경을 확인해야 한다면 MacDate의 원격 Mac 이용 안내에서 현재 방식이 팀의 보안·운영 조건에 맞는지 검토하면 됩니다.