Android 內部存儲 (/data/data/package_name/files/) 是應用私有、無需權限、卸載自動清理、相對安全的持久化區域。通過 Context.openFileInput/Output 進行文件 I/O 是基礎技能。本文系統梳理 API 用法、模式選擇、流操作模式、異步封裝、序列化策略、加密存儲與避坑指南。
// Context 方法
FileInputStream openFileInput(String name) // 讀取
FileOutputStream openFileOutput(String name, int mode) // 寫入
// 模式常量 (可組合 |)
MODE_PRIVATE = 0x00 // 默認:僅當前應用可訪問 (推薦)
MODE_APPEND = 0x2000 // 追加模式
MODE_WORLD_READABLE = 0x01 // 【API 17 棄用】其他應用可讀 (安全風險)
MODE_WORLD_WRITEABLE= 0x02 // 【API 17 棄用】其他應用可寫 (嚴重安全風險)
MODE_MULTI_PROCESS = 0x4 // 【棄用】多進程共享 (不穩定,改用 ContentProvider)
public void writeString(Context context, String filename, String content) {
FileOutputStream fos = null;
try {
fos = context.openFileOutput(filename, Context.MODE_PRIVATE);
fos.write(content.getBytes(StandardCharsets.UTF_8));
} catch (IOException e) {
Log.e("FileIO", "Write failed: " + filename, e);
} finally {
if (fos != null) try { fos.close(); } catch (IOException ignored) {}
}
}
// 追加寫入
public void appendString(Context context, String filename, String content) {
FileOutputStream fos = null;
try {
fos = context.openFileOutput(filename, Context.MODE_PRIVATE | Context.MODE_APPEND);
fos.write(content.getBytes(StandardCharsets.UTF_8));
} catch (IOException e) {
Log.e("FileIO", "Append failed", e);
} finally {
if (fos != null) try { fos.close(); } catch (IOException ignored) {}
}
}
public String readString(Context context, String filename) {
FileInputStream fis = null;
try {
fis = context.openFileInput(filename);
byte[] buffer = new byte[1024];
StringBuilder sb = new StringBuilder();
int len;
while ((len = fis.read(buffer)) != -1) {
sb.append(new String(buffer, 0, len, StandardCharsets.UTF_8));
}
return sb.toString();
} catch (FileNotFoundException e) {
return null; // 文件不存在
} catch (IOException e) {
Log.e("FileIO", "Read failed", e);
return null;
} finally {
if (fis != null) try { fis.close(); } catch (IOException ignored) {}
}
}
// 文件操作結果封裝
sealed class FileResult {
data class Success(val data: T) : FileResult()
data class Failure(val exception: Exception) : FileResult()
}
// 擴展函數:Context 異步文件操作
suspend fun Context.writeFile(
filename: String,
content: String,
mode: Int = MODE_PRIVATE
): FileResult = withContext(Dispatchers.IO) {
try {
openFileOutput(filename, mode).use { it.write(content.toByteArray(Charsets.UTF_8)) }
FileResult.Success(Unit)
} catch (e: Exception) {
FileResult.Failure(e)
}
}
suspend fun Context.readFile(filename: String): FileResult = withContext(Dispatchers.IO) {
try {
openFileInput(filename).use { inputStream ->
FileResult.Success(inputStream.readBytes().decodeToString(Charsets.UTF_8))
}
} catch (e: FileNotFoundException) {
FileResult.Failure(e)
} catch (e: Exception) {
FileResult.Failure(e)
}
}
// 對象序列化 (Kotlinx Serialization / Gson / ProtoBuf)
@Serializable data class UserConfig(val theme: String, val fontSize: Float, val notifications: Boolean)
suspend fun Context.saveConfig(config: UserConfig): FileResult = withContext(Dispatchers.IO) {
try {
val json = Json.encodeToString(config)
writeFile("config.json", json).getOrThrow()
FileResult.Success(Unit)
} catch (e: Exception) {
FileResult.Failure(e)
}
}
suspend fun Context.loadConfig(): FileResult = withContext(Dispatchers.IO) {
try {
val json = readFile("config.json").getOrThrow()
FileResult.Success(Json.decodeFromString(json))
} catch (e: Exception) {
FileResult.Failure(e)
}
}
// 大文件順序寫入:FileOutputStream + BufferedOutputStream
fun writeLargeData(context: Context, filename: String, data: ByteArray) {
context.openFileOutput(filename, MODE_PRIVATE).use { fos ->
BufferedOutputStream(fos, 8192).use { bos ->
bos.write(data)
}
}
}
// 大文件映射讀取 (MappedByteBuffer,零拷貝,適合隨機訪問大文件)
fun readLargeFileMapped(context: Context, filename: String): MappedByteBuffer? {
val file = context.getFileStreamPath(filename)
return RandomAccessFile(file, "r").channel.map(
FileChannel.MapMode.READ_ONLY, 0, file.length()
)
}
// build.gradle.kts
implementation("androidx.security:security-crypto:1.1.0-alpha06")
// 生成/獲取主鑰
val masterKey = MasterKey.Builder(context)
.setKeyScheme(MasterKey.KeyScheme.AES256_GCM)
.build()
// 加密文件讀寫 (自動處理加密/解密、完整性校驗)
val encryptedFile = EncryptedFile.Builder(
File(context.filesDir, "secret.dat"),
context,
masterKey,
EncryptedFile.FileEncryptionScheme.AES256_GCM_HKDF_4KB
).build()
// 寫入
encryptedFile.openFileOutput().use { it.write(secretData) }
// 讀取
val data = encryptedFile.openFileInput().readBytes()
// 獲取文件對象 (可用於長度、刪除、修改時間、FileProvider)
File file = context.getFileStreamPath(filename);
// 列舉所有文件
String[] files = context.fileList();
// 刪除文件
boolean deleted = context.deleteFile(filename);
// 文件大小
long size = context.getFileStreamPath(filename).length();
// 判斷存在
boolean exists = context.getFileStreamPath(filename).exists();
錯誤:多進程直接用 openFileInput/Output → 數據競爭、損壞。
正確:
android:process=":remote" 隔離進程,IPC 序列化訪問FileChannel.lock() 獨佔鎖 (僅同進程內多線程有效,跨進程需 FileLock 支持,Android 實現不穩定)| 問題 | 原因 | 解決 |
|---|---|---|
| 主線程 IO 導致 ANR | 大文件讀寫阻塞 UI 線程 | 協程 Dispatchers.IO / 線程池 / IntentService / WorkManager |
| MODE_APPEND 內容重複/亂碼 | 多線程並發追加無同步 | 單線程序列化寫入、文件鎖、改用數據庫 |
| 文件名包含非法字符導致創建失敗 | / : * ? " < > | 等 | 文件名過濾/轉義、使用 UUID/時間戳命名 |
| 內部存儲空間不足 | 緩存未清理、大文件堆積 | 定期清理、LRU 策略、getCacheDir() 存放可清理緩存 |
| 加密文件讀取失敗 | MasterKey 丟失/不一致 | MasterKey 持久化存儲 (Android Keystore)、備份恢復流程 |
| 存儲類型 | 適用場景 | 容量 | 查詢 | 線程安全 | 跨進程 |
|---|---|---|---|---|---|
| 內部存儲 (File) | 私有文件、序列化對象、日誌、證書、小型二進制 | 應用配額 (通常充足) | 全文掃描 | 需自行同步 | ContentProvider |
| 外部存儲 (公共) | 用戶可見媒體、文檔、下載、跨應用共享 | 用戶磁盤空間 | MediaStore/SAF | 系統管理 | 原生支持 |
| SharedPreferences | 鍵值配置、輕量狀態、首選項 | 小 (< 1MB 建議) | 鍵值查找 | 單進程安全 | ContentProvider |
| Room (SQLite) | 結構化數據、關聯查詢、大量記錄、離線緩存 | 大 (GB 級) | SQL/流式查詢 | 支持 (WAL 模式) | ContentProvider |
內部存儲文件讀寫是 Android 持久化的基石。掌握 Context 文件 API、異步協程封裝、序列化選型、加密方案、多進程協作模式,能構建健壯、安全、高性能的本地存儲層。