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)安装完成后建议先更新下 Homebrewbrew 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. 安装与配置 CocoapodsRuby 环境准备妥当后终于可以安装 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_profile4. 在 Unity 项目中集成 Cocoapods现在来到最核心的部分 - 将 Cocoapods 集成到 Unity 的工作流中。Unity 官方提供了 External Dependency Manager (EDM) 这个工具来简化 iOS 依赖管理。首先需要在 Unity 中安装 EDM。可以通过 Package Manager 安装打开 Window Package Manager点击左上角的 按钮选择 Add package from git URL输入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 LANGen_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. 常见问题排查即使按照上述步骤操作有时还是会遇到各种问题。这里分享几个我遇到过的典型问题及解决方法问题1pod install 执行失败提示找不到命令解决方法检查环境变量配置确保 /usr/local/bin 在 PATH 中。可以尝试在终端直接输入 pod --version 看是否能正确输出版本号。问题2安装时出现权限错误解决方法尽量不要使用 sudo 安装 gem。如果必须使用安装完成后可能需要修复权限sudo chown -R $(whoami) /usr/local/lib/ruby/gems问题3Unity 导出后 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 setup7. 进阶技巧多团队协作配置当项目需要多人协作时Cocoapods 的配置可能会因为环境差异导致问题。这里分享几个确保团队一致性的技巧在项目中添加 .ruby-version 文件指定 Ruby 版本echo 3.2.2 .ruby-version使用 Bundler 管理 gem 依赖。首先安装 Bundlergem install bundler然后在项目根目录创建 Gemfilesource https://gems.ruby-china.com/ gem cocoapods, 1.15.2团队成员只需要运行bundle install bundle exec pod install这样可以确保所有人使用相同版本的 Cocoapods避免因为版本差异导致的问题。8. 性能优化与最佳实践经过多个项目的实践我总结出一些优化 Cocoapods 使用体验的技巧使用并行安装在 pod install 时添加 --parallel 参数可以加快安装速度pod install --parallel清理缓存当遇到奇怪的依赖问题时可以尝试清理缓存pod cache clean --all选择性更新不需要每次都更新全部依赖可以只更新特定 podpod update [POD_NAME]使用 CDN 源在 Podfile 顶部添加以下内容可以加速依赖下载source https://cdn.cocoapods.org/预下载依赖对于 CI/CD 环境可以预先下载依赖pod install --repo-update