はじめに
先日、Railsアプリで使用している image_processing gem を 2.0 にアップデートしました。
CIは無事グリーンになったのですが、その後 GitHub Actions でのデプロイが rails build で失敗するという問題に遭遇しました。
この記事では、その原因と解決策、そして背景にある仕様変更について整理します。
image_processing 2.0 の変更点
CHANGELOG によると、2.0 における最大の破壊的変更はこれです。
mini_magick / ruby-vips がソフト依存（soft dependency）になった
- 1.x 系では
image_processingをインストールすればmini_magickやruby-vipsも自動的に引き込まれていました。 - 2.0 からは、使用するバックエンドに応じて Gemfile に明示的に記載する必要があります。
gem "image_processing", "~> 2.0" gem "mini_magick", "~> 5.0" # ImageMagick を使う場合 gem "ruby-vips", "~> 2.0" # libvips を使う場合
補足：ruby-vips と libvips の関係**
ruby-vipsは C ライブラリであるlibvipsの Ruby バインディングです。ruby-vipsgem をインストールしても、OS にlibvipsの共有ライブラリ（例：libvips42）が存在しないと実行時にエラーになります。- 両者はセットで必要であることを意識しておく必要があります。
起きたこと：CIは通るのに、デプロイで失敗する
アップデート後、Gemfile に ruby-vips を追記したところ、ローカルとCIでのテストは問題なく通りました。
しかし、StagingにデプロイするGitHub Actions ワークフローが rails build のステップで失敗しました。
Error: libvips is required but was not found
原因：GitHub Actions ランナーに libvips がインストールされていない
ruby-vips gem は require 時に libvips の共有ライブラリを ruby-ffi 経由でロードしようとします。
デプロイ用のランナー上には libvips が存在しないため、Bundler.require が走る rails build のタイミングでエラーになっていました。
解決策：require: false を指定する
デプロイの過程（ビルドステップ）では ruby-vips を require する必要はありません。
libvips が必要なのは、実際にアプリが画像処理を行う実行時だけです。
そのため、Gemfile を以下のように修正しました。
gem "ruby-vips", require: false
require: false を指定すると、Bundler.require が呼ばれても自動的に require "vips" されなくなります。
アプリケーション内で実際に ImageProcessing::Vips を使う箇所では、libvips が OS にインストールされた環境（本番サーバーなど）で正常に動作します。
補足：require: false
- Bundler はアプリ起動時にGemfile に記載された gem を一括で
requireします。 require: falseを付けると、この自動 require の対象から除外されます。- gem 自体はロードパスに追加されるので、必要なタイミングで手動
require "vips"することも可能です。 - 今回のケースのように「インストールはしたいが、起動時に require させたくない」という場合に有効な手段です。
別の解決策：GitHub Actions ランナーに libvips をインストールする
もし CI・デプロイ両方のワークフローで libvips を require したい場合は、ワークフロー定義に以下のようなステップを追加する方法もあります。
- name: Install libvips run: sudo apt-get install -y libvips42
ただし今回は、デプロイのビルドステップで libvips が必要な理由がなかったため、require: false での対処がよりシンプルでした。
まとめ
| 内容 | |
|---|---|
| 変更点 | image_processing 2.0 で ruby-vips がソフト依存になり、Gemfile への明示的な記載が必要になった |
| 発生した問題 | デプロイ用 GitHub Actions ランナーに libvips がなく、rails build が失敗した |
| 解決策 | gem "ruby-vips", require: false を指定し、ビルドステップでの自動 require を防いだ |
同じ問題で詰まっている方の参考になれば幸いです。
