Mac M1设备下Rails项目安装PG gem失败无法执行bundle求助

故障根因 #

pg gem编译时依赖PostgreSQL客户端开发库及pg_config配置工具，报错显示系统缺少对应头文件和配置工具，ARM架构下常因架构不兼容、依赖包路径未正确指定触发该问题。

解决方案 #

步骤1：安装PostgreSQL客户端开发依赖

• ARM架构Mac（M1/M2/M3系列）：
  执行brew install libpq
• Debian/Ubuntu ARM服务器：
  执行sudo apt update && sudo apt install -y libpq-dev
• RHEL/CentOS/Fedora ARM服务器：
  执行sudo dnf install -y postgresql-devel

步骤2：手动指定路径安装对应版本pg gem

• ARM架构Mac：
  brew安装的libpq默认pg_config路径为/opt/homebrew/opt/libpq/bin/pg_config，直接执行命令：
  gem install pg -v '1.2.3' -- --with-pg-config=/opt/homebrew/opt/libpq/bin/pg_config
• Linux ARM：
  先执行which pg_config获取配置工具绝对路径，将路径替换到下方命令对应位置执行：
  gem install pg -v '1.2.3' -- --with-pg-config=/你的/pg_config/绝对路径

步骤3：全局配置Bundler避免后续重复报错

执行以下命令将pg的编译参数永久写入Bundler配置，之后直接执行bundle install即可正常识别：

• ARM架构Mac：
  bundle config build.pg --with-pg-config=/opt/homebrew/opt/libpq/bin/pg_config
• Linux ARM：
  bundle config build.pg --with-pg-config=/你的/pg_config/绝对路径

常见排坑点 #

• 确认终端、Homebrew、Ruby均为ARM原生架构编译，混x86与ARM架构的依赖会直接导致安装失败，可执行ruby -e "p RUBY_PLATFORM"验证Ruby架构，输出含arm64即为原生ARM版本
• 若本地安装了完整PostgreSQL服务而非仅libpq，需将pg_config路径替换为PostgreSQL安装目录下对应路径，例如/opt/homebrew/opt/postgresql@15/bin/pg_config
• rbenv管理的Ruby若为x86架构编译，需在原生ARM终端下重新执行rbenv install 2.7.1替换为ARM版本

内容的提问来源于stack exchange，提问作者max.jos