WHAT - 依赖管理工具 CocoaPods

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. 总结

关键点：
✅ React Native 的 iOS 原生模块需要 CocoaPods 来正确链接。
✅ 必须使用 .xcworkspace 打开 Xcode 项目（而不是 .xcodeproj）。
✅ Expo 托管项目不需要 CocoaPods，但裸 React Native 项目需要。