Xcode 환경 세팅 및 애뮬레이터 띄우기 !

🎯 mac (React Native) Xcode 환경세팅 쉽게하기 (따라만 하세요!)

React Native로 iOS 앱을 개발하려면 macOS, Xcode, CocoaPods, React Native CLI 환경이 모두 올바르게 설치되어 있어야 합니다.
처음 세팅할 때 가장 많이 겪는 문제가 Xcode 설치 미완료, CocoaPods 설치 실패, pod 명령어 인식 안 됨 같은 부분이에요.

이 글에서는 초보자도 완전히 따라 할 수 있는 환경세팅 전체 과정을 정리합니다.
미래의 나도 다시 읽고 바로 따라 할 수 있도록 아주 꼼꼼하게 설명합니다.

---

📌 목차

1. Xcode란?
   1-1. Xcode 다운로드(App Store에서 설치)
2. React Native 프로젝트 생성(VS Code)
3. CocoaPods / Pod란? 개념 쉽게 설명
4. CocoaPods 설치하기(순서를 반드시 지켜야 함)
5. 설치가 잘 되었는지 확인하는 방법
6. iOS 앱 실행하기(run-ios)
7. Xcode에서 직접 빌드하는 방법

---

1️⃣ Xcode란?

React Native에서 iOS 앱을 실행하려면 iOS 시뮬레이터, iOS 빌드 환경, iOS SDK가 필요합니다.
이 모든 기능이 Apple의 공식 개발 툴인 Xcode에 포함되어 있습니다.

즉, Xcode가 없으면 iOS 앱을 만들 수도, 실행할 수도, 빌드할 수도 없습니다.

Xcode가 하는 역할:

• iOS 시뮬레이터 실행
• iOS용 앱 빌드
• JavaScript → iOS native 코드 컴파일
• Pods(라이브러리) 통합
• 네이티브 코드 확인/수정

---

1-1️⃣ Xcode 다운로드(App Store)

1. 맥에서 App Store 실행
2. 검색창에 "Xcode" 입력
3. 다운로드(무료)
4. 설치 완료 후 Xcode를 한 번 실행해 "추가 컴포넌트 설치"까지 완료

📌 이 단계 중요합니다.
Xcode를 설치만 하고 처음 실행하지 않으면 iOS 빌드 도구가 설치되지 않습니다.

---

2️⃣ React Native 프로젝트 생성(VS Code 기반)

터미널에서 원하는 작업폴더로 이동하세요:

cd ~/Desktop/폴더 생성할 위치

React Native CLI 공식 방식으로 프로젝트 생성:

npx @react-native-community/cli init 프로젝트명

완료되면:

cd 프로젝트명 code .

VS Code가 열리면 프로젝트 내부를 확인할 수 있습니다.

안 열리면 vscode에서 폴더 열기로 불러오기

---

3️⃣ CocoaPods / pod란? 

React Native는 내부적으로 iOS 네이티브 라이브러리(앱의 실제 동작 부분) 들과 연결됩니다.
이 연결을 관리하는 도구가 CocoaPods입니다.

CocoaPods는 아래 두 가지 역할을 합니다.

✔ 1. iOS 라이브러리 설치(pods)

예:

• react-native-safe-area-context
• react-native-reanimated
• react-native-gesture-handler

✔ 2. Xcode 프로젝트와 연결

설치된 Pod들이 Xcode에서 인식될 수 있도록 자동 설정파일 생성.

---

📌 정리

CocoaPods = iOS용 npm 같은 존재

npm install → node_modules 설치
pod install → Pods 설치

즉, "pod install"은 iOS 개발자라면 무조건 해야 하는 작업입니다.

---

4️⃣ CocoaPods 설치하기(터미널에서)

4-1. Homebrew 업데이트

brew update

4-2. Ruby 설치 (macOS 기본 Ruby는 오래됨)

brew install ruby

4-3. CocoaPods 설치

brew install cocoapods

4-4. PATH 등록 (pod 인식 안 되는 문제 90% 해결)

echo 'export PATH="/opt/homebrew/opt/ruby/bin:$PATH"' >> ~/.zshrc
echo 'export PATH="/opt/homebrew/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

(한줄씩 입력!!)

---

5️⃣ CocoaPods 설치 확인

아래 명령어 실행:

pod --version

버전 숫자가 나오면 완전 성공입니다.

예)

1.15.2

---

6️⃣ iOS 실행 준비(pod install)

React Native 프로젝트의 ios 폴더로 이동:

cd 프로젝트명/ios 
pod install

📌 실행 중 “Analyzing dependencies” 등이 나오면 정상입니다.

이제 iOS 빌드 준비 완료!

---

6️⃣ React Native에서 iOS 앱 실행(run-ios)

프로젝트 최상단 폴더에서:

cd .. //최상단으로 이동해야함
npx react-native run-ios

 

잠시 후 자동으로 iPhone 시뮬레이터가 등장하며 앱이 실행됩니다.

첫 빌드는 오래 걸릴 수 있음! (1~5분)

---

7️⃣ Xcode에서 직접 빌드하기(더 안정적인 방법)

터미널에서:

open ios/프로젝트명.xcworkspace

 

📌 반드시 .xcworkspace 파일을 열어야 합니다.
.xcodeproj를 열면 Pods가 인식되지 않아 빌드가 실패합니다.

Xcode가 열리면:

• 상단 디바이스 선택(iPhone 15, iPhone 14 등)
• ▶︎ 버튼(빌드/실행) 클릭

이 방법이 run-ios보다 안정적입니다.

 

저는 이 방법을 해보진 않았습니다 혹시나 해보시고 잘 된다면 댓글 부탁드립니다..!! ㅎㅎ

---

🎉 마무리

여기까지 하면 macOS에서 React Native + iOS 개발 환경이 완벽하게 구축됩니다.

이 글은:

• React Native iOS 환경세팅 실패한 사람
• pod 오류 때문에 고통받는 사람

모두를 위한 “실수 없는 환경세팅 가이드”로 만들었습니다.

필요한 모든 개념과 순서를 포함하였으니,
이대로만 진행하면 누구든 iOS 환경세팅을 끝낼 수 있습니다.