active-storage-setup

Rails 8 的 Active Storage 设置

概述

Active Storage 用于处理 Rails 中的文件上传：

• 云存储（S3、GCS、Azure）或本地磁盘
• 图像变体（缩略图、调整大小）
• 从浏览器直接上传
• 多态附件

快速开始

# Install Active Storage (if not already)
bin/rails active_storage:install
bin/rails db:migrate

# Add image processing
bundle add image_processing

配置

存储服务

# config/storage.yml
local:
  service: Disk
  root: <%= Rails.root.join("storage") %>

test:
  service: Disk
  root: <%= Rails.root.join("tmp/storage") %>

amazon:
  service: S3
  access_key_id: <%= Rails.application.credentials.dig(:aws, :access_key_id) %>
  secret_access_key: <%= Rails.application.credentials.dig(:aws, :secret_access_key) %>
  region: eu-west-1
  bucket: <%= Rails.application.credentials.dig(:aws, :bucket) %>

google:
  service: GCS
  credentials: <%= Rails.root.join("config/gcs-credentials.json") %>
  project: my-project
  bucket: my-bucket

环境配置

# config/environments/development.rb
config.active_storage.service = :local

# config/environments/production.rb
config.active_storage.service = :amazon

模型附件

单个附件

# app/models/user.rb
class User < ApplicationRecord
  has_one_attached :avatar

  # With variant defaults
  has_one_attached :avatar do |attachable|
    attachable.variant :thumb, resize_to_limit: [100, 100]
    attachable.variant :medium, resize_to_limit: [300, 300]
  end
end

多个附件

# app/models/event.rb
class Event < ApplicationRecord
  has_many_attached :photos

  has_many_attached :documents do |attachable|
    attachable.variant :preview, resize_to_limit: [200, 200]
  end
end

TDD 工作流

Active Storage Progress:
- [ ] Step 1: Add attachment to model
- [ ] Step 2: Write model spec for attachment
- [ ] Step 3: Add validations (type, size)
- [ ] Step 4: Create upload form
- [ ] Step 5: Handle in controller
- [ ] Step 6: Display in views
- [ ] Step 7: Test upload flow

测试附件

请参阅 testing.md，了解模型规格、工厂特征和请求规格。

常见模式：

• 在请求规格中使用 fixture_file_upload
• 使用 after(:build) 定义 :with_avatar 工厂特征
• 在模型规格中测试 be_attached 和变体是否存在

验证

使用 active_storage_validations gem 进行声明式验证，或编写手动 validate 方法。两种方法详见 validations.md。

# Gemfile
gem 'active_storage_validations'

图像变体

在模型附件上使用 resize_to_fill、resize_to_limit 或 resize_to_cover 定义命名变体。有关变体操作、视图辅助方法和表单示例，请参阅 variants-and-views.md。

控制器和服务处理

• 单个上传需允许 :avatar，多个上传需允许 photos: []
• 使用 purge 移除附件，可选择返回 Turbo Stream 响应
• 使用 rails_blob_path 或 send_data 下载文件

完整控制器示例、服务方法、直接上传设置和性能提示，请参阅 controller-and-service.md。

检查清单

• 已安装并迁移 Active Storage
• 已配置存储服务
• 已添加图像处理 gem（如果使用变体）
• 已向模型添加附件
• 已添加验证（类型、大小）
• 已定义变体
• 控制器允许附件参数
• 表单支持文件上传
• 已编写附件测试
• 已配置直接上传（如需要）

参考资料

• testing.md - 模型规格、工厂特征、请求规格
• validations.md - 基于 gem 和手动验证的示例
• variants-and-views.md - 变体定义、视图辅助方法、上传表单
• controller-and-service.md - 控制器、服务方法、直接上传、性能