Mac 下 Ruby 与 Cocoapods 环境搭建：从基础配置到自动化集成

1. 环境准备：从零搭建 Ruby 与 Cocoapods 基础环境

刚接触 iOS 开发的 Unity 开发者经常会遇到一个头疼的问题：明明在 Unity 里跑得好好的项目，导出 Xcode 工程后却各种依赖缺失。这时候就需要 Cocoapods 这个 iOS 生态的包管理工具出场了。但别急着安装 Cocoapods，它需要 Ruby 环境作为基础。Mac 虽然自带 Ruby，但系统自带的版本往往比较旧，直接使用会遇到各种兼容性问题。

我刚开始接触这块时，曾经因为直接用系统 Ruby 安装 Cocoapods 导致各种报错，浪费了大半天时间。后来才发现，正确的姿势应该是先搭建一个独立的 Ruby 开发环境。这里推荐使用 Homebrew 来管理 Ruby 版本，它能帮我们避开很多坑。

首先打开终端，运行以下命令安装 Homebrew：

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

安装完成后，建议先更新下 Homebrew：

brew update

接下来就可以用 Homebrew 安装最新版 Ruby 了：

brew install ruby

安装完成后，需要配置环境变量让系统优先使用我们新安装的 Ruby。编辑你的 shell 配置文件（如果是 bash 就是 ~/.bash_profile，如果是 zsh 就是 ~/.zshrc），添加以下内容：

export PATH="/usr/local/opt/ruby/bin:$PATH"

然后执行 source 命令使配置生效：

source ~/.bash_profile # 或者如果是 zsh source ~/.zshrc

现在运行 ruby -v 应该就能看到新安装的 Ruby 版本了。我最近一次安装时版本是 3.2.2，比系统自带的 2.6.3 新了不少。

2. 配置 RubyGems 镜像加速安装

有了正确的 Ruby 环境后，接下来要配置 RubyGems 的镜像源。默认的 rubygems.org 在国内访问速度很慢，经常导致安装失败。这里推荐使用国内的镜像源。

先查看当前源：

gem sources -l

如果显示的是 https://rubygems.org/，就需要移除它并添加国内镜像：

gem sources --remove https://rubygems.org/ gem sources -a https://gems.ruby-china.com/

这个步骤看似简单，但很多新手会忽略。我曾经因为没换源，安装 Cocoapods 时卡了半小时毫无进展。换了国内源后，安装过程通常只需要几分钟。

3. 安装与配置 Cocoapods

Ruby 环境准备妥当后，终于可以安装 Cocoapods 了。根据你的 macOS 版本，安装命令略有不同：

对于 macOS 10.11 及以后版本：

sudo gem install -n /usr/local/bin cocoapods

安装完成后，需要初始化本地仓库：

pod setup

这个步骤会下载 Cocoapods 的 master 仓库，体积比较大（大约 1GB），可能需要一些时间。我建议在网速好的时候进行，或者使用手机热点有时反而更快。

安装完成后，可以通过以下命令检查版本：

pod --version

如果遇到 "pod: command not found" 的错误，可能是环境变量问题。可以尝试：

export PATH=/usr/local/bin/pod:$PATH echo 'export PATH=/usr/local/bin/pod:$PATH' >> ~/.bash_profile source ~/.bash_profile

4. 在 Unity 项目中集成 Cocoapods

现在来到最核心的部分 - 将 Cocoapods 集成到 Unity 的工作流中。Unity 官方提供了 External Dependency Manager (EDM) 这个工具来简化 iOS 依赖管理。

首先需要在 Unity 中安装 EDM。可以通过 Package Manager 安装：

1. 打开 Window > Package Manager
2. 点击左上角的 "+" 按钮，选择 "Add package from git URL"
3. 输入：https://github.com/googlesamples/unity-jar-resolver.git

安装完成后，在 Assets > External Dependency Manager > iOS Resolver > Settings 中，确保 Cocoapods Integration 设置为 "Xcode Workspace - Add Cocoapods to the Xcode Workspace"。

这个设置很关键，我之前因为没配置这个选项，导致每次导出工程后都要手动执行 pod install。正确的配置可以让 Unity 在导出 Xcode 工程时自动生成 Podfile 文件。

5. 自动化 pod install 流程

虽然 EDM 已经帮我们做了很多工作，但每次导出 Xcode 工程后还是需要手动执行 pod install。对于频繁导出的开发流程来说，这还是很麻烦。我们可以通过 Unity 的 PostProcessBuild 特性来自动化这个过程。

创建一个新的 Editor 脚本（比如叫 AutoPodInstall.cs），添加以下内容：

using UnityEngine; using UnityEditor; using UnityEditor.Callbacks; using System.Diagnostics; using System.IO; using System.Text; public class AutoPodInstall { [PostProcessBuild(999)] public static void OnPostProcessBuild(BuildTarget target, string path) { if (target == BuildTarget.iOS) { PodInstall(path); } } static void PodInstall(string xcodePath) { string shPath = Path.Combine(xcodePath, "podinstall.sh"); StringBuilder sb = new StringBuilder(); sb.AppendLine("#!/bin/sh"); sb.AppendLine("export LANG=en_US.UTF-8"); sb.AppendLine("cd " + xcodePath); sb.AppendLine("pod install"); File.WriteAllText(shPath, sb.ToString()); Process process = new Process(); process.StartInfo.FileName = "sh"; process.StartInfo.Arguments = "podinstall.sh"; process.StartInfo.CreateNoWindow = true; process.StartInfo.UseShellExecute = false; process.StartInfo.WorkingDirectory = xcodePath; process.Start(); process.WaitForExit(); process.Close(); } }

这个脚本会在每次构建完成后自动生成一个 shell 脚本并执行 pod install。我在实际项目中用这个方法节省了大量重复操作的时间。

6. 常见问题排查

即使按照上述步骤操作，有时还是会遇到各种问题。这里分享几个我遇到过的典型问题及解决方法：

问题1：pod install 执行失败，提示找不到命令解决方法：检查环境变量配置，确保 /usr/local/bin 在 PATH 中。可以尝试在终端直接输入 pod --version 看是否能正确输出版本号。

问题2：安装时出现权限错误解决方法：尽量不要使用 sudo 安装 gem。如果必须使用，安装完成后可能需要修复权限：

sudo chown -R $(whoami) /usr/local/lib/ruby/gems

问题3：Unity 导出后 Podfile 没有自动生成解决方法：检查 EDM 的设置是否正确，确保 iOS Resolver 已启用。有时需要手动点击 Assets > External Dependency Manager > iOS Resolver > Install Cocoapods。

问题4：网络问题导致 pod setup 或 pod install 失败解决方法：可以尝试更换网络环境，或者使用以下命令指定使用国内镜像：

pod repo remove master pod repo add master https://mirrors.tuna.tsinghua.edu.cn/git/CocoaPods/Specs.git pod setup

7. 进阶技巧：多团队协作配置

当项目需要多人协作时，Cocoapods 的配置可能会因为环境差异导致问题。这里分享几个确保团队一致性的技巧：

1. 在项目中添加 .ruby-version 文件，指定 Ruby 版本：

echo "3.2.2" > .ruby-version

2. 使用 Bundler 管理 gem 依赖。首先安装 Bundler：

gem install bundler

然后在项目根目录创建 Gemfile：

source 'https://gems.ruby-china.com/' gem 'cocoapods', '1.15.2'

团队成员只需要运行：

bundle install bundle exec pod install

这样可以确保所有人使用相同版本的 Cocoapods，避免因为版本差异导致的问题。

8. 性能优化与最佳实践

经过多个项目的实践，我总结出一些优化 Cocoapods 使用体验的技巧：

1. 使用并行安装：在 pod install 时添加 --parallel 参数可以加快安装速度：

pod install --parallel

2. 清理缓存：当遇到奇怪的依赖问题时，可以尝试清理缓存：

pod cache clean --all

3. 选择性更新：不需要每次都更新全部依赖，可以只更新特定 pod：

pod update [POD_NAME]

4. 使用 CDN 源：在 Podfile 顶部添加以下内容可以加速依赖下载：

source 'https://cdn.cocoapods.org/'

5. 预下载依赖：对于 CI/CD 环境，可以预先下载依赖：

pod install --repo-update