Rails中Active Storage从ImageMagick迁移至Libvips且避免重生成图片

问题背景 #

我们的Rails 7系统使用Active Storage存储了约5万张照片，通过variant方法生成不同尺寸的变体，此前一直用ImageMagick作为image_processing的后端。现在计划迁移到Libvips（新版本Rails的默认变体处理器），但Libvips要求修改variant的选项哈希格式：

# ImageMagick 原写法
variant(format: :jpg, strip: true, quality: 80)
# Libvips 新写法
variant(format: :jpg, saver: { strip: true, quality: 80 })

Rails通过这个选项哈希唯一识别变体，直接修改选项会触发数十万张现有变体的重生成，这是我们需要避免的。之前尝试过先检测ImageMagick变体是否存在再使用，但Rails 7.1将VariantWithRecord#processed?设为私有方法，该方案无法持续使用。

可行解决方案 #

方案1：自定义变体缓存键生成逻辑 #

Active Storage的变体缓存键基于选项哈希生成，我们可以重写缓存键的生成逻辑，让新旧选项格式生成相同的键，从而匹配现有变体文件。

创建初始化文件config/initializers/active_storage_variant_keys.rb：

Rails.application.config.to_prepare do
  ActiveStorage::Variant.class_eval do
    def cache_key
      if options[:saver].present?
        # 将Libvips的saver选项展开为ImageMagick格式的哈希，生成兼容的缓存键
        legacy_options = options.except(:saver).merge(options[:saver])
        ActiveSupport::Cache.expand_cache_key([image.key, "variant", legacy_options], :active_storage_variants)
      else
        super
      end
    end
  end
end

这个方案无需修改数据库或依赖私有方法，是最稳定的过渡方式，新生成的变体也会沿用兼容的缓存键，后续不会有遗留问题。

方案2：批量更新变体记录的元数据 #

如果不想修改缓存键逻辑，可以直接批量更新active_storage_variant_records表中的变体选项，将原ImageMagick格式转换为Libvips兼容格式。

创建Rake任务lib/tasks/active_storage.rake：

namespace :active_storage do
  task migrate_variant_options: :environment do
    ActiveStorage::VariantRecord.find_each do |record|
      next unless record.variation.dig(:format) == :jpg
      
      # 检测并转换ImageMagick格式的选项
      if record.variation.key?(:strip) || record.variation.key?(:quality)
        saver_options = {}
        saver_options[:strip] = record.variation.delete(:strip) if record.variation.key?(:strip)
        saver_options[:quality] = record.variation.delete(:quality) if record.variation.key?(:quality)
        record.variation[:saver] = saver_options
        record.save!
      end
    end
  end
end

运行前务必备份数据库，先在测试环境验证效果，执行命令：

rails active_storage:migrate_variant_options

方案3：过渡阶段的适配器方法 #

如果需要临时兼容两种格式，可封装一个方法，直接检查变体文件是否存在（绕过私有方法限制）：

# 在模型或辅助模块中定义
def compatible_variant(image, options)
  # 生成ImageMagick格式的选项，用于查找现有变体
  magick_options = options.dup
  saver = magick_options.delete(:saver)
  magick_options.merge!(saver) if saver

  variant = image.variant(magick_options)
  # 直接调用service检查文件是否存在
  if variant.send(:service).exist?(variant.send(:key))
    variant
  else
    image.variant(options)
  end
end

这个方法依赖Active Storage内部的key生成逻辑，未来版本可能有变化，适合短期过渡使用。

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