Android 本地儲存圖片不顯示？完整解決方案與權限避坑指南

問題現象

開發拍照功能時，照片儲存代碼執行無報錯，路徑打印正常，但手機相簿、檔案管理器均找不到圖片，甚至無法通過路徑載入圖片。

核心原因分析

1. 缺少儲存權限宣告：Android 6.0+ 需動態申請 WRITE_EXTERNAL_STORAGE，舊版需在 Manifest 靜態宣告
2. 儲存路徑不當：直接寫入 /data/data/package 等應用私有目錄，系統媒體掃描器無法掃描
3. 未通知媒體資料庫更新：新增檔案後需發送 Intent.ACTION_MEDIA_SCANNER_SCAN_FILE 讓相簿刷新
4. Android 10+ 分區儲存限制：需使用 MediaStore API 或 getExternalFilesDir(Environment.DIRECTORY_PICTURES)

完整解決方案（適用 Android 7.0~14）

1. 權限配置

<!-- AndroidManifest.xml -->
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
<!-- Android 10+ 可選，避免分區儲存限制 -->
<application android:requestLegacyExternalStorage="true" ...>

2. 動態權限申請（基礎框架）

// Activity/Fragment 中
private static final int REQUEST_STORAGE = 100;

private void checkAndRequestPermission() {
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) {
        if (ContextCompat.checkSelfPermission(this, Manifest.permission.WRITE_EXTERNAL_STORAGE) 
                != PackageManager.PERMISSION_GRANTED) {
            ActivityCompat.requestPermissions(this, 
                new String[]{Manifest.permission.WRITE_EXTERNAL_STORAGE}, REQUEST_STORAGE);
        } else {
            saveImageToGallery(bitmap);
        }
    } else {
        saveImageToGallery(bitmap);
    }
}

@Override
public void onRequestPermissionsResult(int requestCode, @NonNull String[] permissions, @NonNull int[] grantResults) {
    if (requestCode == REQUEST_STORAGE && grantResults.length > 0 
            && grantResults[0] == PackageManager.PERMISSION_GRANTED) {
        saveImageToGallery(bitmap);
    } else {
        Toast.makeText(this, "需要儲存權限才能保存圖片", Toast.LENGTH_SHORT).show();
    }
}

3. 通用儲存邏輯（支援分區儲存）

private void saveImageToGallery(Bitmap bitmap) {
    String fileName = "IMG_" + System.currentTimeMillis() + ".jpg";
    
    // 1. 獲取標準圖片目錄（自動適配 Android 10+ 分區儲存）
    File directory = getExternalFilesDir(Environment.DIRECTORY_PICTURES);
    // 或公開目錄：Environment.getExternalStoragePublicDirectory(Environment.DIRECTORY_PICTURES)
    
    if (directory == null) {
        Log.e("SaveImage", "無法獲取儲存目錄");
        return;
    }
    
    File imageFile = new File(directory, fileName);
    
    try (FileOutputStream fos = new FileOutputStream(imageFile)) {
        bitmap.compress(Bitmap.CompressFormat.JPEG, 90, fos);
        fos.flush();
        
        // 2. 關鍵步驟：通知媒體掃描器刷新相簿
        MediaScannerConnection.scanFile(this, 
            new String[]{imageFile.getAbsolutePath()}, 
            new String[]{"image/jpeg"}, 
            (path, uri) -> Log.d("SaveImage", "掃描完成: " + uri));
        
        runOnUiThread(() -> Toast.makeText(this, "已保存至相簿: " + imageFile.getAbsolutePath(), Toast.LENGTH_LONG).show());
        
    } catch (IOException e) {
        Log.e("SaveImage", "保存失敗", e);
        runOnUiThread(() -> Toast.makeText(this, "保存失敗: " + e.getMessage(), Toast.LENGTH_SHORT).show());
    }
}

4. 進階：使用 MediaStore（Android 10+ 推薦）

@RequiresApi(api = Build.VERSION_CODES.Q)
private void saveImageToMediaStore(Bitmap bitmap) {
    ContentValues values = new ContentValues();
    values.put(MediaStore.Images.Media.DISPLAY_NAME, "IMG_" + System.currentTimeMillis() + ".jpg");
    values.put(MediaStore.Images.Media.MIME_TYPE, "image/jpeg");
    values.put(MediaStore.Images.Media.RELATIVE_PATH, Environment.DIRECTORY_PICTURES + "/MyApp");
    
    Uri uri = getContentResolver().insert(MediaStore.Images.Media.EXTERNAL_CONTENT_URI, values);
    if (uri != null) {
        try (OutputStream os = getContentResolver().openOutputStream(uri)) {
            bitmap.compress(Bitmap.CompressFormat.JPEG, 90, os);
            Toast.makeText(this, "保存成功", Toast.LENGTH_SHORT).show();
        } catch (IOException e) {
            getContentResolver().delete(uri, null, null); // 失敗時清理
            Log.e("SaveImage", "MediaStore 保存失敗", e);
        }
    }
}

常見坑位總結

除錯技巧

• 使用 adb shell ls -la /sdcard/Pictures/ 直接檢查檔案是否存在
• 在 Android/data/com.your.package/files/Pictures/ 檢查應用專屬目錄
• Logcat 過濾 MediaScanner 觀察掃描日誌

總結

Android 圖片儲存「看似簡單，實則坑多」：權限→路徑→掃描 三步缺一不可。建議統一封裝 ImageSaver 工具類，內部根據 API Level 自動選擇傳統路徑或 MediaStore，業務層一行代碼調用，徹底屏蔽版本差異。