CocoaPods 是 iOS/macOS 開發 的依賴管理工具（類似 npm 對于 JavaScript 或 pip 對于 Python），主要用于管理 iOS 項目的第三方庫（如 React Native 的原生模塊）。

在 React Native 項目 中，如果使用了 需要原生代碼支持的庫（如 @react-native-async-storage/async-storage、react-native-camera 等），通常需要通過 CocoaPods 來安裝 iOS 原生依賴。

---

1. 什么是 CocoaPods？

• CocoaPods 是 Ruby 編寫的 iOS/macOS 依賴管理工具。
• 它通過 Podfile 文件定義項目依賴，并自動下載和鏈接原生庫（.framework 或 .xcframework）。
• React Native 的 iOS 原生模塊 通常需要 CocoaPods 來正確集成。

---

2. 如何安裝 CocoaPods？

(1) 確保已安裝 Ruby（macOS 默認自帶）

ruby -v  # 檢查是否安裝（macOS 通常預裝）

如果未安裝，可以通過 rbenv 或 rvm 安裝 Ruby。

(2) 安裝 CocoaPods

sudo gem install cocoapods

（如果遇到權限問題，可以嘗試 brew install cocoapods 通過 Homebrew 安裝）

(3) 驗證安裝

pod --version  # 應該輸出版本號（如 1.12.1）

---

3. 在 React Native 項目中使用 CocoaPods

(1) 進入 iOS 目錄

React Native 項目的 iOS 原生代碼位于 ios/ 文件夾：

cd your-react-native-project/ios

(2) 初始化 Podfile（如果不存在）

pod init

這會生成 Podfile，其中定義了 iOS 項目的依賴。

(3) 安裝依賴

pod install

這會根據 Podfile 下載并安裝所有 iOS 原生依賴，并生成一個 .xcworkspace 文件（必須使用 .xcworkspace 打開項目，而不是 .xcodeproj）。

(4) 打開 Xcode 項目

open YourProject.xcworkspace

（重要：以后都要用 .xcworkspace 打開，否則原生依賴可能無法正確鏈接）

---

4. React Native 中常見的 CocoaPods 使用場景

(1) 安裝需要原生支持的 React Native 庫

例如，安裝 @react-native-async-storage/async-storage：

npm install @react-native-async-storage/async-storage
# 或
yarn add @react-native-async-storage/async-storage

然后進入 ios/ 并運行：

pod install

這樣 AsyncStorage 的 iOS 原生代碼會被正確鏈接。

(2) 更新 CocoaPods 依賴

如果 Podfile 更新了（如添加了新庫），需要重新運行：

pod install

或者更新現有依賴：

pod update

(3) 清理 CocoaPods 緩存

如果遇到依賴問題，可以清理緩存：

pod cache clean --all

然后重新 pod install。

---

5. 常見問題

(1) pod install 失敗

• 可能原因：
  • Ruby 版本問題（建議使用 rbenv 或 rvm 管理 Ruby）。
  • 網絡問題（嘗試 pod repo update 更新 CocoaPods 源）。
  • Podfile 格式錯誤（檢查語法）。
• 解決方案：

  pod repo update  # 更新 CocoaPods 源
  pod install      # 重新安裝
  

(2) Xcode 打不開項目？

• 必須使用 .xcworkspace 打開，而不是 .xcodeproj（否則原生依賴不會生效）。

(3) Expo 項目需要 CocoaPods 嗎？

• Expo 托管項目（expo init）：不需要，Expo 已經處理了原生依賴。
• Expo 開發構建（eas build）或裸 React Native 項目：需要 CocoaPods 來管理 iOS 原生依賴。

---

6. 總結

操作	命令
安裝 CocoaPods	sudo gem install cocoapods
進入 iOS 目錄	cd ios
初始化 Podfile	pod init
安裝依賴	pod install
更新依賴	pod update
清理緩存	pod cache clean --all
打開 Xcode 項目	open YourProject.xcworkspace

關鍵點：
? React Native 的 iOS 原生模塊需要 CocoaPods 來正確鏈接。
? 必須使用 .xcworkspace 打開 Xcode 項目（而不是 .xcodeproj）。
? Expo 托管項目不需要 CocoaPods，但裸 React Native 項目需要。