需先配置 ruby 环境（推荐 rvm 安装 3.1.4+）、更换为 ruby china 镜像源、再用 --user-install 等方式安装 cocoapods，接着以 --depth 1 克隆 specs 仓库初始化 repo，最后验证 pod --version 和 pod install 是否成功。
一、确认并配置 Ruby 环境
Ruby 是 CocoaPods 的运行基础，macOS 自带 Ruby，但版本常过旧或权限受限，易导致 gem 安装失败。需验证版本并确保使用受信源与可写路径。
1、在终端中执行 ruby -v 查看当前 Ruby 版本；若低于 3.0，建议升级。
2、执行 which ruby 确认 Ruby 路径；若为 /usr/bin/ruby，说明是系统自带版本，不推荐直接使用。
3、推荐使用 RVM 管理 Ruby：运行 curl -sSL https://get.rvm.io | bash -s stable 安装 RVM，然后执行 source ~/.rvm/scripts/rvm 并 rvm install 3.1.4（或最新稳定版）。
4、切换至新版本：rvm use 3.1.4 --default，再验证 ruby -v 和 gem -v 是否同步更新。
二、更换 RubyGems 镜像源（国内加速必备）
默认 RubyGems 源（https://rubygems.org/）在国内访问极不稳定，常引发超时、SSL 错误或 FetchError，必须替换为可信国内镜像。
1、查看当前源：gem sources -l
2、移除官方源：gem sources --remove https://rubygems.org/
3、添加 Ruby China 镜像：gem sources -a https://gems.ruby-china.com/
4、确认生效：gem sources -l 输出应仅含 https://gems.ruby-china.com/，且末尾显示 *** CURRENT。
三、安装 CocoaPods（多路径兼容方案）
不同 macOS 版本与芯片架构（Intel/M1/M2/M3）对安装路径和依赖有差异，以下提供三种互斥但均验证有效的安装方式。
1、标准用户级安装（推荐，避免 sudo 权限风险）：gem install cocoapods --user-install
2、指定 bin 路径安装（适配 Catalina 及之后系统）：sudo gem install -n /usr/local/bin cocoapods
3、M1/M2/M3 芯片专用方案（需 Rosetta 支持 ffi）：
① 打开“终端”应用，右键“显示简介”，勾选 以 Rosetta 方式打开；
② 执行 sudo gem install ffi；
③ 再执行 sudo gem install cocoapods。
四、初始化本地仓库（pod setup 替代方案）
传统 pod setup 命令会下载完整 Specs 仓库（超 1GB），极易卡死或中断。推荐使用轻量、可控的替代流程。
1、清空旧仓库缓存：rm -rf ~/.cocoapods/repos
2、创建 repos 目录：mkdir -p ~/.cocoapods/repos
3、克隆精简版 master 仓库（仅首层提交，秒级完成）：git clone --depth 1 https://github.com/CocoaPods/Specs.git ~/.cocoapods/repos/master
4、验证索引可用：pod repo list 应显示 master 条目且路径正确。
五、验证安装与基础使用
安装完成后需验证命令是否可调用、环境是否隔离正常，并测试最简集成流程。
1、检查版本：pod --version 应输出非空数字（如 1.15.2）。
2、进入任意 iOS 项目目录，创建最小 Podfile：echo "platform :ios, '14.0'\ntarget 'MyApp' do\n use_frameworks!\n pod 'AFNetworking', '~> 4.0'\nend" > Podfile
3、执行依赖解析：pod install；成功后生成 .xcworkspace 文件，且控制台无 ERROR 或 FATAL 提示。
4、若报 [!] Unable to find a specification for 'xxx'，立即执行 pod repo update 同步远程索引。
