macOS Big Sur安装Jekyll时原生扩展构建失败的问题求助

核心报错根因 #

本次报错不是Ruby环境配置异常、也不是缺少libffi系统依赖，本质是已安装的Xcode命令行工具未完成许可协议确认，系统拦截了clang编译器的执行权限，导致ffi原生扩展无法完成编译链接。

分步修复操作 #

• 自动完成Xcode许可协议确认
  在终端执行以下命令，输入当前用户登录密码即可跳过手动逐行阅读许可文本的流程，自动完成许可确认：
  sudo xcodebuild -license accept
• 校验命令行工具链路可用性
  执行路径校验命令，确认命令行工具的配置路径正确：
  xcode-select -p
  正常输出应为/Library/Developer/CommandLineTools，如果输出路径异常，执行路径重置命令：
  sudo xcode-select --switch /Library/Developer/CommandLineTools
  再通过简单编译测试验证编译器权限是否正常：
  echo 'int main(){}' | clang -o /tmp/conftest && /tmp/conftest && echo "编译链路正常"
  无报错输出即代表编译器权限已恢复。
• 清理失败安装缓存后重装
  删除之前编译失败残留的ffi gem缓存目录，避免旧的错误日志、残留目标文件干扰重新安装：
  rm -rf ~/.gem/ruby/3.0.0/gems/ffi-1.15.0 ~/.gem/ruby/3.0.0/extensions/x86_64-darwin-20/3.0.0/ffi-1.15.0
  重新执行用户级gem安装命令：
  gem install --user-install bundler jekyll

注意事项 #

• 安装完成后需确认用户级gem的可执行目录已加入shell的PATH环境变量，否则会出现终端无法识别jekyll命令的问题。对应当前环境的用户级gem路径为/Users/tgermer/.gem/ruby/3.0.0/bin，可在对应shell配置文件（zsh为~/.zshrc，bash为~/.bash_profile）中添加配置行：
  export PATH="$HOME/.gem/ruby/3.0.0/bin:$PATH"
• 全程保持--user-install的用户级安装方式，不要切换root用户执行安装命令，避免污染Homebrew安装的Ruby全局目录权限。

内容的提问来源于stack exchange，提问作者TGermer