CocoaPods安装需先配置Ruby环境：用Homebrew安装独立Ruby（避开系统Ruby权限问题），更换为Ruby China镜像源，执行gem install cocoapods（不加sudo），再pod setup初始化Specs仓库，最后在项目目录运行pod init和pod install完成接入。
如果你正在为iOS项目引入AFNetworking、SDWebImage等第三方库，却还在手动拖文件、配Build Settings、加Link Binary，那CocoaPods能帮你把整个依赖流程压缩成一条命令——但前提是它得先在Mac终端里正确装好。
确认系统与基础环境
打开终端，先执行sw_vers，确保 macOS 版本不低于 Sonoma（14.0）；低于 Ventura（13.0）的旧系统可能触发 SIP 限制导致后续 gem 安装失败。
输入which ruby，若返回路径含 /usr/bin/ruby，说明你正使用系统自带 Ruby——【这是不可跳过的风险点】，它受 SIP 保护，无法写入 gem 目录，强行安装会报 Permission denied 错误。
再运行git --version，必须有输出且版本 ≥ 2.30；若提示 command not found，请先安装 Xcode Command Line Tools：xcode-select --install，弹窗点“Install”即可。
切换到安全可用的 Ruby 环境
推荐用 Homebrew 安装独立 Ruby，彻底避开系统 Ruby 权限陷阱。
若尚未安装 Homebrew，粘贴运行：/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
安装完成后执行：brew install ruby
将新 Ruby 加入 PATH：Apple Silicon Mac 运行 echo 'export PATH="/opt/homebrew/bin:$PATH"' >> ~/.zshrc；Intel Mac 改为 /usr/local/bin。
重载配置：source ~/.zshrc，再用 ruby -v 验证——输出应为 3.1 或更高版本，且 which ruby 返回路径必须含 /opt/homebrew/bin/ruby 或 /usr/local/bin/ruby。
更换 RubyGems 源并安装 CocoaPods
国内直连 rubygems.org 极大概率超时失败，必须换源。
方法一（推荐）：用 Ruby China 镜像
执行 gem sources --remove https://rubygems.org/ → gem sources -a https://gems.ruby-china.org/ → gem sources -l，确认输出中仅剩 https://gems.ruby-china.org/。
方法二（备用）：若 Ruby China 不可用，改用 tuna：gem sources -a https://pypi.tuna.tsinghua.edu.cn/simple/（注意：此地址实际为 PyPI 镜像，仅作临时兜底，不保证长期有效）。
执行安装命令：gem install cocoapods。【切勿加 sudo】——加了反而会写入系统目录，导致后续 pod 命令找不到可执行文件。
初始化本地 Specs 仓库
这一步拉取的是 CocoaPods 的全部开源库索引，体积超 1.2GB，首次运行需耐心等待。
第一步：执行 pod setup，终端会显示 Setting up CocoaPods master repo 并开始克隆。
第二步：若卡在 Cloning into 'master'... 超过 5 分钟，新开一个终端窗口，运行：cd ~/.cocoapods/repos && du -sh *，观察 master 文件夹大小是否持续增长；若停滞不动，执行：git config --global http.postBuffer 524288000，再回到原窗口按 Ctrl + C 中断，重新运行 pod setup。
第三步：当终端打印出 Setup completed，即表示本地索引已就绪。
验证安装并接入首个项目
在任意空目录下执行：pod --version，有数字输出（如 1.15.2）即成功。
进入你的 iOS 项目根目录（必须含 .xcodeproj 文件），运行：pod init，生成默认 Podfile。
用文本编辑器打开 Podfile，取消注释并修改 platform 行，例如：platform :ios, '15.0'；在 target 'YourApp' do 区块内添加一行：pod 'AFNetworking'。
保存后执行：pod install，等待完成，出现 Pods-YourApp.xcworkspace 文件即表示接入成功。
