carrierwave-video未执行视频转码却直接上传原文件至S3求助

我之前在结合CarrierWave、CarrierWave-Video和Sidekiq做视频后台转码上传时，也碰到过一模一样的问题。咱们从几个核心环节一步步排查：

1. 确认CarrierWave-Video的Uploader配置是否正确 #

首先要确保你在上传器类里正确调用了转码处理方法，并且参数配置无误。比如：

class VideoUploader < CarrierWave::Uploader::Base
  include CarrierWave::Video
  include CarrierWave::Video::Thumbnailer # 如果需要生成缩略图的话

  # 核心：指定转码格式和参数，比如转成MP4、调整分辨率
  process encode: [:mp4, resolution: "640x480"]

  # 存储配置（比如S3）
  storage :fog

  # 其他常规配置，比如允许的文件类型
  def extension_allowlist
    %w(mp4 mov avi mkv)
  end
end

注意：如果你的转码参数写错（比如格式拼写错误、分辨率格式不对），ffmpeg可能会静默失败，导致直接上传原文件。

2. 检查后台处理的配置是否生效 #

CarrierWave-Backgrounder的配置如果不到位，会直接跳过转码步骤，直接上传原文件：

模型层配置 #

确保你的模型里使用了process_in_background指定要后台处理的上传字段：

class Video < ApplicationRecord
  mount_uploader :file, VideoUploader
  process_in_background :file # 关键：把视频上传转成后台任务
end

初始化配置 #

在config/initializers/carrierwave_backgrounder.rb里确认后台适配器设置为Sidekiq：

CarrierWave::Backgrounder.configure do |c|
  c.backend :sidekiq, queue: :video_transcode # 指定单独的队列方便管理
end

ActiveJob适配器设置 #

确保Rails的ActiveJob使用Sidekiq作为适配器，在config/application.rb或者对应环境的配置文件里：

config.active_job.queue_adapter = :sidekiq

3. 验证转码依赖是否安装 #

CarrierWave-Video依赖FFmpeg，如果环境里没装FFmpeg或者路径不对，转码会直接失败，转而上传原文件：

• 执行命令ffmpeg -version，确认能正常输出版本信息
• 如果是服务器环境，确保FFmpeg已经安装（比如Ubuntu用apt install ffmpeg，CentOS用yum install ffmpeg）

4. 检查Sidekiq进程是否在运行 #

后台任务需要Sidekiq进程来处理，如果你没启动Sidekiq，转码任务会堆积在队列里，原文件会直接被上传：

• 启动Sidekiq：bundle exec sidekiq -q video_transcode（指定我们之前配置的队列）
• 打开Sidekiq的Web界面（如果配置了），查看是否有失败的任务，失败任务的日志会告诉你具体原因（比如FFmpeg执行报错、权限问题）

5. 排查环境与版本兼容性 #

有时候版本不匹配会导致功能失效：

• 确认carrierwave、carrierwave-video、carrierwave-backgrounder的版本和你的Rails版本兼容（可以查各自的Gem文档）
• 开发环境下，确保没有禁用后台处理（比如有些开发者会在development.rb里临时把ActiveJob适配器改成:inline，这会跳过Sidekiq直接同步执行，但如果转码失败也会直接上传原文件）

最后一步：查看日志 #

如果上面的配置都没问题，去看Rails日志和Sidekiq日志，里面会有转码过程的详细报错信息——比如FFmpeg无法处理原视频格式、文件权限不足、S3存储配置错误等，这些都是导致转码跳过的常见原因。

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