Android 圖片上傳只傳了路徑不傳文件？正確上傳姿勢詳解

問題現象

Android 上傳圖片，服務端只收到一個本地路徑字串（如 /storage/emulated/0/DCIM/xxx.jpg），而非圖片二進制數據。

根本原因

代碼中將 文件路徑字串 作為請求參數發送，而非將 文件流 作為 multipart/form-data 部分上傳。常見錯誤代碼：

// 錯誤：只發送路徑字串
RequestBody body = new FormBody.Builder()
    .add("imagePath", picturePath) // 這只是字串
    .build();

正確做法：Multipart 上傳文件流

使用 OkHttp 3.x/4.x（推薦）

File file = new File(picturePath);
RequestBody fileBody = RequestBody.create(MediaType.parse("image/jpeg"), file);
RequestBody requestBody = new MultipartBody.Builder()
    .setType(MultipartBody.FORM)
    .addFormDataPart("image", file.getName(), fileBody) // 關鍵：文件名、文件流、MIME 類型
    .addFormDataPart("userId", "123") // 其他表單字段
    .build();

Request request = new Request.Builder()
    .url(UPLOAD_URL)
    .post(requestBody)
    .build();

client.newCall(request).enqueue(new Callback() { ... });

使用 Retrofit 2.x（更優雅）

// 接口定義
@Multipart
@POST("upload")
Call<ResponseBody> uploadImage(@Part MultipartBody.Part image, @Part("userId") RequestBody userId);

// 調用
File file = new File(picturePath);
RequestBody requestFile = RequestBody.create(MediaType.parse("image/*"), file);
MultipartBody.Part part = MultipartBody.Part.createFormData("image", file.getName(), requestFile);
RequestBody userId = RequestBody.create(MediaType.parse("text/plain"), "123");

service.uploadImage(part, userId).enqueue(new Callback<ResponseBody>() { ... });

服務端接收要點

• Spring MVC：@RequestParam("image") MultipartFile file
• Node.js：multer 中間件
• PHP：$_FILES['image']

服務端拿到的是文件流，可直接保存、處理。

圖片參考

常見坑點避雷

• 大文件 OOM：OkHttp 預設會將整個文件讀入內存構建 RequestBody。超大文件（>50MB）建議使用 Okio.source(file) 流式構建或分片上傳。
• 權限：Android 10+ 需適配 Scoped Storage，使用 MediaStore 或 FileProvider 獲取可讀 URI，不可直接用絕對路徑 new File(path)。
• 網絡超時：設置合理的 connectTimeout、writeTimeout、readTimeout。
• MIME 類型：根據實際圖片格式設置 image/jpeg、image/png 等，或通用 image/*。

總結

Android 圖片上傳必須使用 multipart/form-data 將文件流 作為 Part 發送，而非路徑字串。OkHttp/Retrofit 均提供完善的 Multipart 支持，配合服務端 MultipartFile 接收，即可正確實現文件上傳。