Rails Git post-receive钩子无法启动Puma的问题排查

核心原因是Git post-receive钩子运行在非交互式、非登录SSH会话中，这类会话默认不会加载~/.profile或~/.bashrc等环境配置文件。你的Rails 6服务器SSH连接会自动加载~/.profile，说明其钩子运行时能获取到完整的环境变量（比如Ruby版本管理工具的路径、bundle命令路径）；而Rails 7服务器的钩子因为缺少环境变量，导致bundle命令无法被正确识别，进而Puma无法自动启动。

具体解决步骤 #

• 手动加载环境配置到钩子脚本开头
  在post-receive脚本的最顶部添加环境加载命令，根据你使用的Ruby版本管理工具选择：

  • 若用rbenv：

    export PATH="$HOME/.rbenv/bin:$PATH"
    eval "$(rbenv init -)"
    source ~/.profile
    

  • 若用rvm：

    source "$HOME/.rvm/scripts/rvm"
    source ~/.profile
    

  直接加载~/.profile可以确保钩子获得和你手动登录时一致的环境变量，但要确保.profile里没有仅针对交互式shell的代码（比如echo提示语），避免干扰脚本执行。

• 确保脚本切换到正确的工作目录
  检查钩子脚本中是否明确切换到了Rails 7项目的根目录，比如：

  cd /path/to/your/rails7/api/app || exit 1
  

  这一步很关键，否则bundle和Puma配置文件都会找不到。

• 用绝对路径调用bundle（可选）
  如果加载环境后仍有问题，可以直接用bundle的绝对路径调用，先在服务器手动执行which bundle得到路径，比如~/.rbenv/shims/bundle，然后把脚本中的bundle替换为这个绝对路径：

  ~/.rbenv/shims/bundle exec puma -C config/puma.rb -e production > /dev/null 2>&1 &
  

• 调试钩子输出，定位具体错误
  暂时去掉Puma启动命令的静默输出，改为写入日志文件，方便排查问题：

  bundle exec puma -C config/puma.rb -e production >> /var/log/rails7_puma_deploy.log 2>&1 &
  

  部署后查看日志文件，就能看到启动失败的具体原因（比如依赖未安装、配置文件错误等）。

• 确认钩子脚本的执行权限
  确保post-receive脚本有可执行权限：

  chmod +x /path/to/repo/hooks/post-receive
  

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