基于Rails后端的移动端如何通过API使用Activestorage直传？

安全阿岳

2026-5-22

使用Rails Active Storage实现移动端（Android/iOS）直传API

我刚好做过类似的移动端对接Rails Active Storage直传的项目，给你分享下可行的方案和实践经验：

一、官方原生API直传方案（无需逆向解析）

其实Active Storage本身就提供了直传的API端点，可能你没注意到官方文档里的细节，这个方案是最稳妥的，不需要去逆向解析前端JS。

1. 后端基础配置

首先确保Active Storage已经正确安装：

rails active_storage:install
rails db:migrate

默认情况下，Rails已经挂载了Active Storage的路由（在config/routes.rb里会有mount ActiveStorage::Engine => '/rails/active_storage'），其中直传的核心端点是POST /rails/active_storage/direct_uploads。

如果你的移动端和API跨域，需要配置CORS，在config/initializers/cors.rb里添加：

Rails.application.config.middleware.insert_before 0, Rack::Cors do
  allow do
    origins '*' # 生产环境务必替换成你的移动端合法域名/IP
    resource '/rails/active_storage/*', 
      headers: :any, 
      methods: [:get, :post, :put, :delete]
  end
end

2. 移动端直传的完整流程

直传分为获取上传凭证和上传文件到云存储两步：

第一步：向Rails请求上传凭证

移动端需要先发送POST请求到/rails/active_storage/direct_uploads，携带文件的基本信息：

{
  "blob": {
    "filename": "avatar.jpg",
    "content_type": "image/jpeg",
    "byte_size": 102400, // 文件字节大小
    "checksum": "abcdef1234567890..." // 文件的SHA256校验和（十六进制字符串）
  }
}

请求成功后，Rails会返回包含直传信息的响应，核心字段是direct_upload：

{
  "direct_upload": {
    "url": "https://your-cloud-storage-bucket.s3.amazonaws.com/xxx",
    "headers": {
      "Content-Type": "image/jpeg",
      "Authorization": "AWS4-HMAC-SHA256 Credential=xxx...",
      // 其他云存储要求的签名头
    },
    "blob_id": "abc123..." // 后续关联模型要用的Blob ID
  }
}

第二步：直接上传文件到云存储

拿到响应里的url和headers后，移动端用PUT方法把文件上传到这个云存储地址，请求头严格按照返回的headers设置，文件内容作为请求体发送。

上传完成后，你就可以把blob_id关联到你的业务模型（比如创建User时带上avatar_blob_id: "abc123..."）。

二、逆向解析activestorage.js的实践经验

如果你确实需要复刻前端JS的逻辑，其实activestorage.js的核心就是上面的两步，我之前研究过它的源码，关键点有这些：

校验和计算：Rails用的是文件的SHA256哈希，转成十六进制字符串，必须和后端计算一致，否则会返回422错误。
请求细节：获取凭证的POST请求必须是JSON格式，上传到云存储用PUT方法，不能用POST。
进度监听：activestorage.js会监听XMLHttpRequest的上传进度，移动端可以根据需求实现类似的进度回调。

举个Android端计算SHA256校验和的Kotlin示例：

fun calculateFileSHA256(file: File): String {
    val digest = MessageDigest.getInstance("SHA-256")
    file.inputStream().use { inputStream ->
        val buffer = ByteArray(8192)
        var bytesRead: Int
        while (inputStream.read(buffer).also { bytesRead = it } != -1) {
            digest.update(buffer, 0, bytesRead)
        }
    }
    return digest.digest().joinToString("") { "%02x".format(it) }
}

三、常见坑点注意

跨域拦截：如果移动端是WebView或者直接调用API，必须确保CORS配置正确，否则请求会被拦截。
文件大小限制：Rails默认有参数大小限制，同时要调整Nginx/Apache的上传大小限制，避免大文件上传失败。
校验和不匹配：一定要保证移动端计算的SHA256和Rails一致，比如注意文件编码、读取方式，不要漏读字节。

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

基于Rails后端的移动端如何通过API使用Activestorage直传？

一、官方原生API直传方案（无需逆向解析） #

1. 后端基础配置 #

2. 移动端直传的完整流程 #