CocoaPods安装失败主因是Ruby链接了Homebrew版OpenSSL导致TLS握手失败；需通过dyld_print_libs确认SSL路径，用brew reinstall ruby --build-from-source修复链接，并清理证书缓存。
cocoapods 在 macos 上安装失败，常不是它自身的问题，而是底层 ruby 环境或系统动态库（尤其是 openssl、libcurl、zlib）被 homebrew 或手动安装的版本干扰所致。系统自带的 /usr/lib/libssl.dylib 等受 sip 保护、版本固定，而 cocoapods（尤其通过 gem install cocoapods 安装时）依赖的 ruby 可能链接了 /opt/homebrew/lib/libssl.3.dylib 这类新版库——一旦 abi 不兼容，就会在 pod setup 或 pod install 阶段报错，如：
-
dyld: Library not loaded: /opt/homebrew/opt/openssl@3/lib/libssl.3.dylib -
SSL_connect returned=1 errno=0 state=error: sslv3 alert handshake failure -
Failed to connect to github.com port 443: Connection refused（实为 TLS 握手失败）
关键不在重装 CocoaPods，而在理清 Ruby 和其依赖库的真实链接路径。
确认 Ruby 正在加载哪个 SSL 库
运行以下命令，看实际加载行为：
dyld_print_libs=1 ruby -e "require 'openssl'" 2>&1 | grep -i ssl
如果输出中出现 /opt/homebrew/.../libssl.3.dylib，说明 Ruby 被“劫持”了；若显示 /usr/lib/libssl.dylib，则问题可能出在证书链或网络配置。
修复 Ruby 的动态库链接（推荐）
Homebrew 安装的 Ruby（如 brew install ruby）默认会正确链接自己的 OpenSSL，但系统 Ruby（/usr/bin/ruby）或 rbenv/rvm 管理的 Ruby 若编译时未指定路径，就容易混用。解决方法分两类：
-
如果你用的是 Homebrew Ruby：
brew unlink openssl && brew link --force openssl@3 brew reinstall ruby --build-from-source
--build-from-source确保 Ruby 编译时读取当前openssl@3的头文件与库路径，避免运行时找错符号。 -
如果你用的是 rbenv/rvm 或系统 Ruby：
先检查 Ruby 构建信息：ruby -r rbconfig -e "puts RbConfig::CONFIG['LIBS']"
若含
-lssl但无对应路径，需重新编译：export LDFLAGS="-L$(brew --prefix openssl@3)/lib" export CPPFLAGS="-I$(brew --prefix openssl@3)/include" rbenv install 3.3.0 # 或你当前版本
绕过冲突：临时强制 Ruby 使用系统 SSL（仅调试用）
不推荐长期使用，但可快速验证是否为库冲突：
DYLD_FALLBACK_LIBRARY_PATH="/usr/lib" gem install cocoapods
若成功，说明确实是第三方 OpenSSL 干扰；后续应修复 Ruby 编译环境，而非依赖此方式。
清理残留的证书与配置
CocoaPods 依赖 curl 和系统钥匙串。执行：
security find-certificate -p /System/Library/Keychains/SystemRootCertificates.keychain | sudo tee -a /etc/ssl/cert.pem > /dev/null rm -rf ~/.cocoapods pod setup
这可解决因证书过期或缺失导致的 Could not reach GitHub 类错误。
避免未来冲突的实践建议
- 不要用
sudo gem install，改用gem install --user-install+export GEM_HOME="$HOME/.gem/ruby/$(ruby -e 'puts RUBY_VERSION')" - 在项目根目录加
.ruby-version和.ruby-gemset（rbenv），隔离 Ruby 版本与 Gemset - 对于 Xcode 项目，CocoaPods 本身已支持
use_modular_headers!和disable_input_output_paths!，减少对全局库的隐式依赖
本质上，这不是 CocoaPods 的 bug，而是 macOS 多层库共存机制下的路径优先级问题。定位真实加载库 → 修正 Ruby 构建依赖 → 清理证书缓存，三步到位。
