README

commit信息：Update callbacks in README | 提交者：brucebolt | 提交时间：2020-02-18 | 版本：0c67436

CarrierWave

该工具以一种简单和极其灵活的方式提供了Ruby应用上传文件的功能。
它能与基于Rack的web应用一起很好地工作，例如：Ruby on Rails。

资料

RubyDoc.info上的RDoc文档
GitHub上的源代码
Wiki中有更多关于已知的局限、以及教程的资料

获取帮助

如果你有任何问题，请在Stack Overflow社区寻求帮助。请不要在issue上发起一个如何使用的问题。
请在issue上报告bug，但要首先阅读Wiki上的"getting help"章节。

安装

安装最新版本：

$ gem install carrierwave

在rails中，把它添加到你的Gemfile文件中：

gem 'carrierwave', '~> 2.0'

最后，重启服务来应用这些改变。

对于2.0版本来说，CarrierWave 依赖Rails 5以上版本和Ruby 2.2以上版本。如果你正在使用Rails 4，你应该使用1.x版本。

起步

首先生成uploader：

rails generate uploader Avatar

这会给你生成一个文件：

app/uploaders/avatar_uploader.rb

查看该文件以获取如何定制uploader的提示。它应该看起来像下面这样：

class AvatarUploader < CarrierWave::Uploader::Base
  storage :file
end

你可以像下面这样使用你的uploader 类来存储和取回文件：

uploader = AvatarUploader.new

uploader.store!(my_file)

uploader.retrieve_from_store!('my_file.png')

CarrierWave 给你一个store方法来提供永久储存，以及一个 cache方法来提供临时储存。你可以使用不同的储存系统，包括文件系统和云储存。

大多数时间你想搭配着ORM来使用CarrierWave。在你的模型属性列上挂载uploader是很简单，这样你只需要分派文件即可开始：

ActiveRecord

确保你在加载ORM之后再加载CarrierWave，否则你需要手动请求相关的扩展，即：

require 'carrierwave/orm/activerecord'

使用迁移来向你想挂载uploader的模型里添加一个字符串属性列：

rails g migration add_avatar_to_users avatar:string
rails db:migrate

打开你的模型文件，并且挂载uploader：

class User < ActiveRecord::Base
  mount_uploader :avatar, AvatarUploader
end

现在你可以给属性指派文件来缓存文件，这样当记录被储存后，它们会被自动存储起来。

u = User.new
u.avatar = params[:file] # 像这样指派文件，或者

# 像这样
File.open('somewhere') do |f|
  u.avatar = f
end

u.save!
u.avatar.url # => '/url/to/file.png'
u.avatar.current_path # => 'path/to/file.png'
u.avatar_identifier # => 'file.png'

请注意： u.avatar绝不会返回nil，即使它没有关联任何照片。
为了检查照片是否被保存到模型中，请使用u.avatar.file.nil?来代替。

DataMapper, Mongoid, Sequel

其它的ORM 支持已经被拆解到了一些独立的gem：

在该wiki中有更多的扩展的列表

上传多个文件

CarrierWave有可信赖的多文件上传支持。

ActiveRecord

添加一个可以存放数组的数据列。例如：它可以是一个数组列或者JSON列。你可以依据你的数据库支持来选择其中之一。例如，创建一个像下面一样的迁移：

对ActiveRecord json数据类型支持的数据库来说（即，PostgreSQL, MySQL）

rails g migration add_avatars_to_users avatars:json
rails db:migrate

对不支持ActiveRecord json数据类型的数据库来说（即，SQLite）

rails g migration add_avatars_to_users avatars:string
rails db:migrate

请注意：在SQLite 适配器里不存在JSON 数据类型，那是为什么你要使用string 数据类型的原因，该数据类型将在模型中被解析。

打开你的模型文件，然后挂载该uploader：

class User < ActiveRecord::Base
  mount_uploaders :avatars, AvatarUploader
  serialize :avatars, JSON # If you use SQLite, add this line.
end

请确保使用带着s的(mount_uploaders)来挂载该uploader，而不是(mount_uploader)，这为了避免上传多文件时发生错误。

请确保你的文件input字段被设置为多文件字段。例如，在Rails中，你需要执行以下操作：

<%= form.file_field :avatars, multiple: true %>

同时，请确保你的上传控制器允许该多文件上传属性，在hash中指向一个空数组。例如：

params.require(:user).permit(:email, :first_name, :last_name, {avatars: []})

现在你可以在上传对话框中选择多个文件（像是 SHIFT+SELECT），当记录被储存的时候它们将会被自动存储起来。

u = User.new(params[:user])
u.save!
u.avatars[0].url # => '/url/to/file.png'
u.avatars[0].current_path # => 'path/to/file.png'
u.avatars[0].identifier # => 'file.png'

如果你想在上传新文件时保留现有的文件，你可以像下面这样做：

<% user.avatars.each do |avatar| %>
  <%= hidden_field :user, :avatars, multiple: true, value: avatar.identifier %>
<% end %>
<%= form.file_field :avatars, multiple: true %>

支持通过重排hidden_field来排序头像，这里提供了一个使用JQuery UI Sortable 的例子。

改变储存文件夹

为了改变上传文件的存放位置，只需要复写 store_dir方法：

class MyUploader < CarrierWave::Uploader::Base
  def store_dir
    'public/my/upload/directory'
  end
end

这适用于文件存储以及Amazon S3和Rackspace云文件。
如果你想把文件储存在根目录下，请定义store_dir方法为nil。

如果你想把文件储存在项目根文件夹之外，你可能需要以同样的方式定义cache_dir：

class MyUploader < CarrierWave::Uploader::Base
  def cache_dir
    '/tmp/projectname-cache'
  end
end

上传安全

如果某些文件被上传到错误的地方，可能会非常危险，例如PHP文件或者其他脚本文件。CarrierWave 让你可以指定允许的后缀或者内容类型的白名单。

如果你挂载了该uploader，则上传一个错误后缀的文件将会使记录验证失败。否则，将引发错误。

class MyUploader < CarrierWave::Uploader::Base
  def extension_whitelist
    %w(jpg jpeg gif png)
  end
end

使用内容类型也可以做相同的事情。
比如说我们需要一个只接收图片的uploader。可以像下面这样做

class MyUploader < CarrierWave::Uploader::Base
  def content_type_whitelist
    /image\//
  end
end

你可以使用一个黑名单来拒绝一些内容类型。
比如说我们需要一个uploader来拒绝JSON文件。可以像下面这样做

class NoJsonUploader < CarrierWave::Uploader::Base
  def content_type_blacklist
    ['application/text', 'application/json']
  end
end

CVE-2016-3714 (ImageTragick)

该版的CarrierWave有能力减缓 CVE-2016-3714。然而你必须在你的uploaders里设置content_type_whitelist来使该保护措施生效，并且你也必须关闭ImageMagick的默认SVG委托，或者给SVG处理程序使用RSVG委托。

下面是一个有效的白名单，它约束你的uploader只接受图片同时减轻了CVE：

class MyUploader < CarrierWave::Uploader::Base
  def content_type_whitelist
    [/image\//]
  end
end

警告：content_type_whitelist是CarrierWave支持的唯一一种白名单或者黑名单形式，它能有效缓解CVE-2016-3714攻击。使用extension_whitelist不会检查文件头，该漏洞仍然对你的应用生效。

文件名称和unicode字符

你应该关心的另一个安全issue是文件名（请查看Ruby On Rails安全指南）。
默认CarrierWave只提供英语字母、阿拉伯数字和一些符号作为文件名的白名单列表。如果你想支持本地脚本（Cyrillic 字符、letters with diacritics等），你需要复写sanitize_regexp方法。它应该是匹配所有不被允许字符的正则表达式。

CarrierWave::SanitizedFile.sanitize_regexp = /[^[:word:]\.\-\+]/

请确保不允许拉丁字符，那样将不会造成第三方插件或者客户端软件的兼容性issue。

设置内容类型

对于v0.11.0版本，mime-types gem是一个运行时依赖，因此内容类型会被自动设置。
你不再需要手动做这个。

添加版本

有时你经常想添加同一个文件的不同版本。一个典型的例子是图片缩略图。对此有内置支持*:

请注意：你必须安装Imagemagick才能调整图片大小。

一些文档推荐使用RMagick来代替MiniMagick，但是我们推荐MiniMagick。

为了在OSX中使用homebrew安装Imagemagick，请键入下面代码：

$ brew install imagemagick

class MyUploader < CarrierWave::Uploader::Base
  include CarrierWave::MiniMagick

  process resize_to_fit: [800, 800]

  version :thumb do
    process resize_to_fill: [200,200]
  end

end

当该uploader 被使用时，一个上传的图片将会被缩放不大于到800×800像素。会保持原始的长宽比。

被称为:thumb的版本之后被创建，它将被精确缩放到200×200像素。该缩略图使用resize_to_fill，它会确保该缩略图被设定到指定的宽度和高度，如果原始比例需要剪裁，那就会剪裁。

以上的uploader可能会像下面这样被使用：

uploader = AvatarUploader.new
uploader.store!(my_file)                              # size: 1024x768

uploader.url # => '/url/to/my_file.png'               # size: 800x800
uploader.thumb.url # => '/url/to/thumb_my_file.png'   # size: 200x200

记着一个重要的事情，该程序将在版本创建前调用。这样可以节约程序运行开支。

处理方法： mini_magick

convert -修改图片编码格式到给定格式，像是 jpg
resize_to_limit - 保持原始长宽比来调整图片尺寸到小于指定尺寸。如果它比指定尺寸大，只需调整图片的大小。处理后的图片是更小尺寸时或许比指定尺寸更矮或者更窄。
resize_to_fit -保持原始长宽比来调整图片尺寸到给定尺寸之内。在更小尺寸里，图片或许比指定尺寸更矮或者更窄，但是不会比指定值更大。
resize_to_fill - 保持原始长宽比来调整图片尺寸到给定尺寸之内。如果必须，它会剪裁大尺寸的图片。"gravity"可以被选择性地设置，像是"Center"或者"NorthEast"。
resize_and_pad - 保持原始长宽比来调整图片尺寸到给定尺寸之内。如果需要。它将会使用指定颜色来覆盖剩余区域，（对git和pnd来说）它默认是透明，（对jpeg来说是白色）。"gravity"可以想上面那样被选择性地设置。

请查看carrierwave/processing/mini_magick.rb文件来获取详细信息。

版本嵌套

可以在版本中嵌套版本：

class MyUploader < CarrierWave::Uploader::Base

  version :animal do
    version :human
    version :monkey
    version :llama
  end
end

条件版本

有时候你想基于模型中的某些属性来约束版本的创建，或者基于图片本身。

class MyUploader < CarrierWave::Uploader::Base

  version :human, if: :is_human?
  version :monkey, if: :is_monkey?
  version :banner, if: :is_landscape?

private

  def is_human? picture
    model.can_program?(:ruby)
  end

  def is_monkey? picture
    model.favorite_food == 'banana'
  end

  def is_landscape? picture
    image = MiniMagick::Image.new(picture.path)
    image[:width] > image[:height]
  end

end

该model实例变量会被指代为uploader被添加到的实例对象。

依据存在的版本来创建版本

由于性能原因，经常会使用存在的版本，而不是原始文件来创建新的版本。如果你的uploader生成了一些版本，接下来的版本比之前的版本要小，从更小的已经被处理好的图片那来生成这个版本，会花费更少的时间。

class MyUploader < CarrierWave::Uploader::Base

  version :thumb do
    process resize_to_fill: [280, 280]
  end

  version :small_thumb, from_version: :thumb do
    process resize_to_fill: [20, 20]
  end

end

该:from_version选项使用在:thumb版本里的缓存文件，而不是原文件，可能有更快的处理速度。

使上传跨表单重新显示有效

你会经常地注意到在验证失败时上传的文件将会消失。
在那种情况下，CarrierWave有一些功能来轻松地记着已上传的文件。设想你有一个user模型，有一个 uploader挂载到avatar文件，只需要添加一个被称为 avatar_cache的隐藏字段（千万不要忘了把它加入到允许的字段列表中）。在Rails里，它看起来像下面这样：

<%= form_for @user, html: { multipart: true } do |f| %>
  <p>
    <label>My Avatar</label>
    <%= f.file_field :avatar %>
    <%= f.hidden_field :avatar_cache %>
  </p>
<% end %>

显示一个用户已经上传过的文件也许是一个好主意，就图片而言，一个小的缩略图是一个好的标记：

<%= form_for @user, html: { multipart: true } do |f| %>
  <p>
    <label>My Avatar</label>
    <%= image_tag(@user.avatar_url) if @user.avatar? %>
    <%= f.file_field :avatar %>
    <%= f.hidden_field :avatar_cache %>
  </p>
<% end %>

移出上传了的文件

如果你想移出一个之前上传的在挂载的uploaded上的文件，你只需向表单中添加一个复选框，当它被勾选后，该文件将会被移除。

<%= form_for @user, html: { multipart: true } do |f| %>
  <p>
    <label>My Avatar</label>
    <%= image_tag(@user.avatar_url) if @user.avatar? %>
    <%= f.file_field :avatar %>
  </p>

  <p>
    <label>
      <%= f.check_box :remove_avatar %>
      Remove avatar
    </label>
  </p>
<% end %>

如果你想手动移除文件，你可以调用remove_avatar!代码，之后再保存该对象。

@user.remove_avatar!
@user.save
#=> true

从远程地址上传文件

你的用户或许想使用一个URL从一个网络地址中上传一个文件。CarrierWave能轻松地实现该功能，只需往你的表单中添加正确的属性，就像下面这样：

<%= form_for @user, html: { multipart: true } do |f| %>
  <p>
    <label>My Avatar URL:</label>
    <%= image_tag(@user.avatar_url) if @user.avatar? %>
    <%= f.text_field :remote_avatar_url %>
  </p>
<% end %>

如果你使用 ActiveRecord，CarrierWave将标记无效的URLs，并且自动下载失败会带来属性验证错误信息。如果你没有使用ActiveRecord，或者你把CarrierWave的 validate_download选项给关了，这样你需要自己来支持这些错误功能。

提供一个默认URL

在许多情况下，尤其是上传图片时，提供一个默认的URL或许是一个好主意，当没有上传文件时提供备用。通过复写你的uploader中的default_url方法，你可以轻松的达成该功能：

class MyUploader < CarrierWave::Uploader::Base
  def default_url(*args)
    "/images/fallback/" + [version_name, "default.png"].compact.join('_')
  end
end

或者你可以使用Rails资源管道：

class MyUploader < CarrierWave::Uploader::Base
  def default_url(*args)
    ActionController::Base.helpers.asset_path("fallback/" + [version_name, "default.png"].compact.join('_'))
  end
end

再次创建版本

你或许有时想改变一个版本或者添加一个新版本。你可以使用recreate_versions!方法从基础文件再次创建版本。如果没有传递参数，该方法将使用一个简单方式来重新上传，然后处理指定的版本或者所有的版本。

当你生成了一个随机的唯一的文件名时，你必须要在使用了 recreate_versions!后，在该模型上调用save!方法。该操作是必须的，因为recreate_versions!方法不把新文件名保存到数据库。你自己调用save!方法，将会防止数据库和文件系统运行不同步。

instance = MyUploader.new
instance.recreate_versions!(:thumb, :large)

或者在一个挂载了的uploader上：

User.find_each do |user|
  user.avatar.recreate_versions!
end

请注意：recreate_versions!方法将在没有图片的记录上抛出一个异常。为了避免这样请，请只作用到有图片的记录，或者在块儿里检查一个图片是否存在。如果你正在使用ActiveRecord，重新创建用户头像的代码可能看起来像下面这样：

User.find_each do |user|
  user.avatar.recreate_versions! if user.avatar?
end

配置CarrierWave

CarrierWave有宽范围的配置选项，你可以配置作用范围为全局范围或者在每个uploader基础上：

CarrierWave.configure do |config|
  config.permissions = 0666
  config.directory_permissions = 0777
  config.storage = :file
end

或者，也可以这样：

class AvatarUploader < CarrierWave::Uploader::Base
  permissions 0777
end

如果你正在使用Rails，可以像下面这样创建一个初始化程序：

config/initializers/carrierwave.rb

如果你觉得CarrierWave在开发模式中太过吵闹，你可以在你的环境文件中修改这些配置：

CarrierWave.configure do |config|
  config.ignore_integrity_errors = false
  config.ignore_processing_errors = false
  config.ignore_download_errors = false
end

搭配着CarrierWave来进行测试

在隔离区域测试你的uploaders是一个好主意。为了提速你的测试，推荐关闭你测试中的处理程序，之后使用文件储存。在rails里，你可以通过添加一个初始化处理来达到该目的：

if Rails.env.test? or Rails.env.cucumber?
  CarrierWave.configure do |config|
    config.storage = :file
    config.enable_processing = false
  end
end

请记着，如果你已经在你的uploader中设置了storage :something。来自该初始化程序的设置将被忽略。

如果你需要测试你的程序处理，你应该在一个隔离环境中测试它，在需要它的测试中开启处理程序。

CarrierWave随附一些RSpec匹配器，您可能会发现它们有用：

require 'carrierwave/test/matchers'

describe MyUploader do
  include CarrierWave::Test::Matchers

  let(:user) { double('user') }
  let(:uploader) { MyUploader.new(user, :avatar) }

  before do
    MyUploader.enable_processing = true
    File.open(path_to_file) { |f| uploader.store!(f) }
  end

  after do
    MyUploader.enable_processing = false
    uploader.remove!
  end

  context 'the thumb version' do
    it "scales down a landscape image to be exactly 64 by 64 pixels" do
      expect(uploader.thumb).to have_dimensions(64, 64)
    end
  end

  context 'the small version' do
    it "scales down a landscape image to fit within 200 by 200 pixels" do
      expect(uploader.small).to be_no_larger_than(200, 200)
    end
  end

  it "makes the image readable only to the owner and not executable" do
    expect(uploader).to have_permissions(0600)
  end

  it "has the correct format" do
    expect(uploader).to be_format('png')
  end
end

如果你在寻找一些minitest断言，请查看carrierwave_asserts。

在一个uploader上设置enable_processing选项，将会阻止所有版本的处理。
通过像下面这样在版本上设置处理选项，一个版本的处理程序可以被打开：

@uploader.thumb.enable_processing = true

Fog

如果你想使用fog，你必须把下面这行添加到你的CarrierWave初始化程序中

config.fog_credentials = { ... } # Provider specific credentials

正在使用Amazon S3

Fog AWS支持Amazon S3。确保在你的Gemfile文件中添加了它：

gem "fog-aws"

你需要在初始化程序中提供你的fog_credentials和fog_director（又名为bucket）。
因为性能原因，假设该文件夹已经存在，因此如果需要创建它，请创建它。你也可以传递附加选项，在lib/carrierwave/storage/fog.rb有一个充分的文档。下面有一个完整的例子：

CarrierWave.configure do |config|
  config.fog_credentials = {
    provider:              'AWS',                        # required
    aws_access_key_id:     'xxx',                        # required unless using use_iam_profile
    aws_secret_access_key: 'yyy',                        # required unless using use_iam_profile
    use_iam_profile:       true,                         # optional, defaults to false
    region:                'eu-west-1',                  # optional, defaults to 'us-east-1'
    host:                  's3.example.com',             # optional, defaults to nil
    endpoint:              'https://s3.example.com:8080' # optional, defaults to nil
  }
  config.fog_directory  = 'name_of_bucket'                                      # required
  config.fog_public     = false                                                 # optional, defaults to true
  config.fog_attributes = { cache_control: "public, max-age=#{365.days.to_i}" } # optional, defaults to {}
end

在你的uploader里设置储存为:fog

class AvatarUploader < CarrierWave::Uploader::Base
  storage :fog
end

是这样的!对于在Amazon S3上的文件,你仍是需要使用CarrierWave::Uploader#url方法来返回URL。

请注意：为了 Carrierwave能正确的生效，它需要credentials有下面的权限：

s3:ListBucket
s3:PutObject
s3:GetObject
s3:DeleteObject
s3:PutObjectAcl

正在使用Rackspace云文件

Fog用来支持Rackspace云文件。请确保在你的Gemfile文件中添加下面代码：

gem "fog"

你需要在初始化程序中配置一个文件夹，一个用户名和API key。
由于性能原因，它会假设该文件夹已经存在，因此如果它不存在请创建它。

使用一个US-based账号：

CarrierWave.configure do |config|
  config.fog_credentials = {
    provider:           'Rackspace',
    rackspace_username: 'xxxxxx',
    rackspace_api_key:  'yyyyyy',
    rackspace_region:   :ord                      # optional, defaults to :dfw
  }
  config.fog_directory = 'name_of_directory'
end

使用一个UK-based账号：

CarrierWave.configure do |config|
  config.fog_credentials = {
    provider:           'Rackspace',
    rackspace_username: 'xxxxxx',
    rackspace_api_key:  'yyyyyy',
    rackspace_auth_url: Fog::Rackspace::UK_AUTH_ENDPOINT,
    rackspace_region:   :lon
  }
  config.fog_directory = 'name_of_directory'
end

你可以选择在配置文件中包括你的CDN主机名。
该操作被高度推荐，因为没有它的每个请求需要查询此信息.

config.asset_host = "http://c000000.cdn.rackspacecloud.com"

在你的uploader中，设置储存为:fog

class AvatarUploader < CarrierWave::Uploader::Base
  storage :fog
end

是这样的!对于在Rackspace云文件上的文件,你仍是需要使用CarrierWave::Uploader#url方法来返回URL。

对于使用Google存储的开发者

Fog为开发者支持谷歌存储。确保在你的Gemfile文件中添加了它：

gem "fog-google"
gem "google-api-client", "> 0.8.5", "< 0.9"
gem "mime-types"

你将需要在初始程序中配置一个文件夹（又名为bucket）、一个登录key id和一个安全登录key。
由于性能原因，那是假设该文件夹已经存在，因此如果它不存在，请创建它。

关于如何得到credentials，请查阅fog-google README。

CarrierWave.configure do |config|
  config.fog_credentials = {
    provider:                         'Google',
    google_storage_access_key_id:     'xxxxxx',
    google_storage_secret_access_key: 'yyyyyy'
  }
  config.fog_directory = 'name_of_directory'
end

在你的uploader中，设置储存为:fog

class AvatarUploader < CarrierWave::Uploader::Base
  storage :fog
end

是这样的!对于在Google上的文件,你仍是需要使用CarrierWave::Uploader#url方法来返回URL。

优化Fog的加载

因为Carrierwave不知道你想要使用哪部分的Fog，它将加载完整的库（除非你像这样使用：用[fog-aws, fog-google]正确地替代fog）。如果你更喜欢加载较少的类到你的应用中，则需要先加载Fog的这些部分，然后再将CarrierWave加载到Gemfile中。像是：

gem "fog", "~> 1.27", require: "fog/rackspace/storage"
gem "carrierwave"

关于版本的两个注意事项：

此功能在Fog v1.20被添加。
此功能计划用于CarrierWave v1.0.0.

如果你不是一个人配置Gemfile组件，并且在某处依赖了"carrierwave"，请你确保在它之前请求"fog/rackspace/storage"。像是：

require "fog/rackspace/storage"
require "carrierwave"

小心该依赖只在使用fog provider时生效，因此它至今没有被提取到该gem中。
在fog组织页面这里可以发现一个提取的提供者的列表.

当出现问题时，请检视Fog.constants来查看什么被加载了。

动态的资源主机

该asset_host配置选项可以被设计为一个proc(或者其他的返回给call调用的东西)来动态生成主机。该proc-compliant对象使用当前 CarrierWave::Storage::Fog::File或者CarrierWave::SanitizedFile的实例来作为它唯一的参数。

CarrierWave.configure do |config|
  config.asset_host = proc do |file|
    identifier = # some logic
    "http://#{identifier}.cdn.rackspacecloud.com"
  end
end

使用 RMagick

如果你上传图片文件，你可能想以一些方式来处理它们，例如，你或许想创建图片缩略图。CarrierWave 有一个名为RMagick的库来简化图片文件处理，你需要在你的Uploader中包含它：

class AvatarUploader < CarrierWave::Uploader::Base
  include CarrierWave::RMagick
end

该RMagick模块给你一些方法，像是CarrierWave::RMagick#resize_to_fill方法，它以一些方式来处理图片文件。你可以设置一个 process回调，当每次文件被上传时，它会被调用。
这里是一个尺寸调整的例子。
尺寸调整只在文件有相同的文件后缀时生效，也可以使用文件名方法。

class AvatarUploader < CarrierWave::Uploader::Base
  include CarrierWave::RMagick

  process resize_to_fill: [200, 200]
  process convert: 'png'

  def filename
    super.chomp(File.extname(super)) + '.png' if original_filename.present?
  end
end

查看操作！方法，那会让你写自己的处理方法变得简单。

使用MiniMagick

MiniMagick与RMagick相似，但是所有的操作都使用'convert' CLI，那是标准ImageMagick kit中的一部分。它让你有ImageMagick的强大能力，而不必担心安装所有的RMagick库。

了解详情，请查看MiniMagick 的站点：

https://github.com/minimagick/minimagick

为了得到更多提供的功能，请查看ImageMagick命令行选项：

http://www.imagemagick.org/script/command-line-options.php

当前 MiniMagick carrierwave程序提供了像RMagick processor程序一样的方法。

class AvatarUploader < CarrierWave::Uploader::Base
  include CarrierWave::MiniMagick

  process resize_to_fill: [200, 200]
end

从Paperclip上迁移过来

如果你正在使用Paperclip，你可以使用compatibility模块：

class AvatarUploader < CarrierWave::Uploader::Base
  include CarrierWave::Compatibility::Paperclip
end

了解详情，请查看 CarrierWave::Compatibility::Paperclip模块的文档。

请确保挂载到了正确的属性列：

mount_uploader :avatar, AvatarUploader, mount_on: :avatar_file_name

I18n

Active Record验证使用Rails的 i18n框架。那添加这些keys到你的翻译文件中：

errors:
  messages:
    carrierwave_processing_error: failed to be processed
    carrierwave_integrity_error: is not of an allowed file type
    carrierwave_download_error: could not be downloaded
    extension_whitelist_error: "You are not allowed to upload %{extension} files, allowed types: %{allowed_types}"
    extension_blacklist_error: "You are not allowed to upload %{extension} files, prohibited types: %{prohibited_types}"
    content_type_whitelist_error: "You are not allowed to upload %{content_type} files, allowed types: %{allowed_types}"
    content_type_blacklist_error: "You are not allowed to upload %{content_type} files"
    rmagick_processing_error: "Failed to manipulate with rmagick, maybe it is not an image?"
    mini_magick_processing_error: "Failed to manipulate with MiniMagick, maybe it is not an image? Original Error: %{e}"
    min_size_error: "File size should be greater than %{min_size}"
    max_size_error: "File size should be less than %{max_size}"

该carrierwave-i18n库增加了对其他语言环境的支持。

大文件

默认情况下，CarrierWave拷贝上传文件两次，第1次拷贝该文件到缓存中，接下来拷贝该文件到储存里。对于大文件，这可能会消耗太多时间。

你可以通过修改move_to_cache和move_to_store方法中的一个或两个来改变该行为。

class MyUploader < CarrierWave::Uploader::Base
  def move_to_cache
    true
  end

  def move_to_store
    true
  end
end

当move_to_cache 和/或者 move_to_store方法返回true时，文件将被分别移动到缓存和储存，而不是拷贝。

该操作只在本地文件储存中被测试过。

跳过ActiveRecord 回调

默认把uploader 挂载到ActiveRecord模型中，会添加一些回调。比如，下面这个代码：

class User
  mount_uploader :avatar, AvatarUploader
end

它将添加下面这些回调：

before_save :write_avatar_identifier
after_save :store_previous_changes_for_avatar
after_commit :remove_avatar!, on: :destroy
after_commit :mark_remove_avatar_false, on: :update
after_commit :remove_previously_stored_avatar, on: :update
after_commit :store_avatar!, on: [:create, :update]

如果你想跳过这些回调（比如，在上传一个新文件之后，你仍然想保存之前的头像），你可以使用ActiveRecord的skip_callback方法。

class User
  mount_uploader :avatar, AvatarUploader
  skip_callback :commit, :after, :remove_previously_stored_avatar
end

给CarrierWave做贡献

请查阅CONTRIBUTING.md

许可

权限在此被授予，可以自由管控，任何人可以获取该软件和相关的文档，没有约束地出售该软件，包含
但不限于使用，复制，修改，合并，发布，
分发，再许可和/或出售本软件的副本，并
允许使用软件的人也可以这样做，但须遵守
以下条件：

上述版权声明和本许可声明为
本软件包含的所有副本或实质性部分。

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.