Capacitor Datei-Handling-Leitfaden: Lesen, Schreiben, Wählen, Teilen

Capacitor Dateiverwaltung geht auf einige Grundbausteine hinaus: @capacitor/filesystem Dateien in App-Verzeichnissen zu lesen und zu schreiben Capacitor.convertFileSrc to display them, a picker to import user files, and native plugins to download, upload, open and share. This guide shows each one with Capacitor 8 code, explains which directory to use on iOS and Android, and covers the memory and permission traps that cause most file bugs.

Die Dateihandhabungswerkzeugkiste

Installieren Sie das Kern-Plugin zuerst:

bun add @capacitor/filesystem
bunx cap sync

Wählen Sie das richtige Verzeichnis

Jeder Filesystem-Aufruf erfordert ein directory. Die falsche Wahl ist die häufigste Ursache für verlorene Dateien und abgelehnte Apps.

Regeln der Faust:

• Große herunterladbare Medien (Offline-Videos, Kartenbilder) geht in LibraryNoCloud. Apple lehnt Apps ab, die große herunterladbare Inhalte in iCloud-gesicherten Ordner speichern, wie in den iOS-Daten-Speicherleitlinien beschrieben.
• Temporäre Dateien (Exporte, die Sie einmal teilen, Thumbnails) gehen in Cache. Speichern Sie niemals die einzige Kopie von Benutzerdaten dort.
• Dateien, die der Benutzer später außerhalb Ihrer App finden soll gehören nicht in einen App-Ordner überhaupt. Speichern Sie sie über das Teilen, MediaStore Downloads oder den Systemdateiauswahl. Siehe unsere Anleitung zu Android-gekapseltem Speicher in Capacitor.

Eine Datei schreiben

import { Filesystem, Directory, Encoding } from '@capacitor/filesystem';

// Text file
await Filesystem.writeFile({
  path: 'notes/today.txt',
  data: 'Hello from Capacitor',
  directory: Directory.Data,
  encoding: Encoding.UTF8,
  recursive: true, // create notes/ if missing
});

// JSON
await Filesystem.writeFile({
  path: 'settings.json',
  data: JSON.stringify({ theme: 'dark' }),
  directory: Directory.Data,
  encoding: Encoding.UTF8,
});

// Binary file: pass base64 and no encoding
await Filesystem.writeFile({
  path: 'images/logo.png',
  data: base64Png,
  directory: Directory.Data,
  recursive: true,
});

Die encoding Option bestimmt, wie data interpretiert wird. Mit Encoding.UTF8, wird die Zeichenfolge als Text geschrieben. Ohne es, werden native Plattformen die Datei dekodieren. data als Base64 und die Rohdaten schreiben. Vergessen Sie dies und Sie erleben das klassische "Mein PDF ist korrupt"-Fehler.

Um zu einem bestehenden Datei, wie einem Log, hinzuzufügen appendFile Eine Datei lesen

Ein Datei lesen

const { data } = await Filesystem.readFile({
  path: 'settings.json',
  directory: Directory.Data,
  encoding: Encoding.UTF8,
});
const settings = JSON.parse(data as string);

// Binary: returns base64 on native, a Blob on web
const image = await Filesystem.readFile({
  path: 'images/logo.png',
  directory: Directory.Data,
});

, die abgelehnt wird, wenn die Datei fehlt: statGroße Dateien in Blöcken lesen

async function exists(path: string) {
  try {
    await Filesystem.stat({ path, directory: Directory.Data });
    return true;
  } catch {
    return false;
  }
}

Lesen Sie große Dateien in Blöcke

readFile wird die gesamte Datei als eine Basis64-Zeichenkette zurückgegeben. Für ein 200 MB-Video bedeutet dies Hunderte von MB an Zeichenketten im JS-Gedächtnis. readFileInChunks streams es anstatt:

await Filesystem.readFileInChunks(
  { path: 'videos/clip.mp4', directory: Directory.Data, chunkSize: 1024 * 1024 },
  (chunk, err) => {
    if (err) return console.error(err);
    if (chunk === null) return console.log('done');
    processChunk(chunk.data); // base64 chunk
  },
);

Better still, avoid moving the bytes through JS at all. Most “read a big file” tasks are really “upload it” or “display it”, and both have native paths below.

Liste, kopieren, verschieben und löschen

const { files } = await Filesystem.readdir({ path: 'notes', directory: Directory.Data });
for (const f of files) console.log(f.name, f.type, f.size, f.mtime);

await Filesystem.mkdir({ path: 'archive', directory: Directory.Data, recursive: true });

await Filesystem.copy({
  from: 'notes/today.txt',
  to: 'archive/today.txt',
  directory: Directory.Data,
});

await Filesystem.rename({
  from: 'archive/today.txt',
  to: 'archive/2026-10-01.txt',
  directory: Directory.Data,
});

await Filesystem.deleteFile({ path: 'notes/today.txt', directory: Directory.Data });
await Filesystem.rmdir({ path: 'notes', directory: Directory.Data, recursive: true });

copy und rename annehmen toDirectory zum Wechseln zwischen Verzeichnissen, zum Beispiel von Cache zum Data nach Abschluss eines Downloads. Sie akzeptieren auch absolute file:// Pfade, wenn Sie directory, wie Sie Dateien importieren, die von anderen Plugins zurückgegeben werden.

Ein Datei im WebView anzeigen

Laden Sie keine Bilder oder Videos als Base64-Daten-URLs, wenn Sie es vermeiden können. Wandeln Sie den nativen Pfad in eine von Capacitor's lokalen Server bereitgestellte URL um:

import { Capacitor } from '@capacitor/core';

const { uri } = await Filesystem.getUri({ path: 'images/logo.png', directory: Directory.Data });
img.src = Capacitor.convertFileSrc(uri);

Auf iOS sieht das Ergebnis wie capacitor://localhost/_capacitor_file_/...aus, auf Android https://localhost/_capacitor_file_/...Es funktioniert für <img>, <video>, <audio>und fetch(), was bedeutet, dass du auch ein Datei als ein ArrayBuffer ohne Base64:

const buffer = await fetch(Capacitor.convertFileSrc(uri)).then((r) => r.arrayBuffer());

Speichere Pfade, nicht umgewandelte URLs. Die umgewandelte Form ist nur für die aktuelle App-Sitzung gültig.

Wähle Dateien vom Gerät aus

Der Systempicker gibt dem Benutzer die Kontrolle und benötigt keine Speicherberechtigung auf Android 13+ oder iOS:

bun add @capgo/capacitor-file-picker
bunx cap sync

import { CapgoFilePicker } from '@capgo/capacitor-file-picker';

const { files } = await CapgoFilePicker.pickFiles({
  types: ['application/pdf', 'image/*'],
  limit: 5,
  readData: false, // keep false for anything bigger than a few MB
});

for (const file of files) {
  console.log(file.name, file.mimeType, file.size, file.path);
}

Es gibt auch pickImages, pickVideos, pickMedia und pickDirectorycontext convertHeicToJpeg auf iOS. Auf iOS, types nur MIME-Typen, keine Dateierweiterungen.

Gewählte Dateien können sich in einer temporären Location befinden oder hinter einem content:// URI, das nur für eine Weile lesbar ist. Wenn Sie das File später benötigen, kopieren Sie es sofort in Ihren eigenen Verzeichnis. Filesystem.copy.

Dateien herunterladen

Mit Fortschritt: @capacitor/dateiübertragung

Filesystem.downloadFile ist in Filesystem 8 veraltet. Die Ersatzmethode sendet die Antwort direkt auf die Festplatte:

bun add @capacitor/file-transfer
bunx cap sync

import { FileTransfer } from '@capacitor/file-transfer';
import { Directory, Filesystem } from '@capacitor/filesystem';

const { uri } = await Filesystem.getUri({ path: 'downloads/report.pdf', directory: Directory.Data });

const listener = await FileTransfer.addListener('progress', (p) => {
  if (p.lengthComputable) setProgress(p.bytes / p.contentLength);
});

await FileTransfer.downloadFile({
  url: 'https://example.com/report.pdf',
  path: uri,
  progress: true,
  headers: { Authorization: `Bearer ${token}` },
});

await listener.remove();

In den Hintergrund: @capgo/capacitor-herunterladegerät

Für große Dateien, die weiter heruntergeladen werden sollen, wenn der Benutzer die App verlässt, und die pausiert und fortgesetzt werden können, verwenden Sie den Capgo-Herunterladegerät, der auf DownloadManager auf Android und im Hintergrund URLSession auf iOS:

import { CapacitorDownloader } from '@capgo/capacitor-downloader';

await CapacitorDownloader.addListener('downloadProgress', ({ id, progress }) => {
  console.log(id, progress);
});
await CapacitorDownloader.addListener('downloadCompleted', ({ id }) => {
  console.log('done', id);
});

await CapacitorDownloader.download({
  id: 'course-video-12',
  url: 'https://cdn.example.com/course/12.mp4',
  destination: 'videos/12.mp4',
  network: 'wifi-only',
  notification: 'progress', // Android
});

Eine relative destination bezieht sich auf das externe Dateisystem der App auf Android und das Documents Verzeichnis auf iOS, die gleichen Orte wie Directory.External.

Dateien hochladen

Lesen Sie eine Datei nicht in Base64 nur, um sie zu senden. Beide Upload-Optionen lesen direkt von der Festplatte:

import { FileTransfer } from '@capacitor/file-transfer';

const result = await FileTransfer.uploadFile({
  url: 'https://api.example.com/upload',
  path: uri,          // full file:// path
  fileKey: 'file',
  mimeType: 'application/pdf',
  headers: { Authorization: `Bearer ${token}` },
  progress: true,
});
console.log(result.responseCode, result.bytesSent);

For Uploads, die überleben müssen, wenn die App in den Hintergrund geschoben wird (Videos, Batch-Uploads von Fotos), verwenden Sie @capgo/capacitor-uploader, die im Hintergrund läuft URLSession auf iOS und einen Upload-Dienst mit einer Fortschrittsbenachrichtigung auf Android:

import { Uploader } from '@capgo/capacitor-uploader';

const { id } = await Uploader.startUpload({
  filePath: uri,
  serverUrl: 'https://api.example.com/upload',
  method: 'PUT', // binary body, ideal for presigned S3 or R2 URLs
  mimeType: 'video/mp4',
});

Presignierte PUT URLs für Objekt-Speicher sind das zuverlässigste Muster für große Dateien: Ihr API signiert die URL, und das Gerät lädt direkt in den Speicher hoch.

Eine Datei teilen oder exportieren

Lassen Sie den Benutzer ein Datei an eine andere App senden oder speichern, wo sie es finden können:

import { FileSharer } from '@capgo/capacitor-file-sharer';

await FileSharer.share({
  filename: 'report.pdf',
  path: uri,
  contentType: 'application/pdf',
});

// Android: write to Downloads via MediaStore. iOS: opens the share sheet ("Save to Files")
await FileSharer.save({
  filename: 'report.pdf',
  path: uri,
  contentType: 'application/pdf',
});

Der Capgo-Dateiteiler kopiert die Datei in seinen eigenen Cache-Ordner und dient sie über eine dedizierte FileProvider, sodass Sie keine Änderungen vornehmen müssen file_paths.xmlMit der offiziellen @capacitor/shareAndroid kann nur aus dem Cache-Ordner teilen, es sei denn, Sie fügen andere Ordner zu android/app/src/main/res/xml/file_paths.xml.

Eine Datei in einer anderen App öffnen

bun add @capacitor-community/file-opener
bunx cap sync

import { FileOpener } from '@capacitor-community/file-opener';

await FileOpener.open({ filePath: uri, contentType: 'application/pdf' });

On iOS öffnet dies eine Quick Look-Vorschau. Auf Android öffnet es die Standard-App für das MIME-Typ oder zeigt einen Auswahl-Assistenten an. Wenn keine App den Typ handhaben kann, wird die Anfrage abgelehnt, also fangen Sie es und bieten Sie das Teilen an.

Gemeinsame Datei-Rezepte

Erstelle ein PDF: Rendere HTML mit @capgo/capacitor-pdf-generator oder baue es in JS mit pdf-lib, dann schreibe die base64-Ausgabe mit writeFile. Unsere scan to PDF-Tutorial zeigt den vollständigen Workflow.

Entferne GPS aus einer Fotobevor dem Hochladen: @capgo/capacitor-file-compressor entfernt EXIF-Metadaten auf jedem Plattform während der Größe.

Anpassen oder konvertieren Sie ein Bild: Die gleiche Komprimierungssoftware verarbeitet Breite, Höhe, Qualität und Ausgabeformat, einschließlich HEIC zu JPEG.

Viele Dateien in einem Bundle: Ein Ordner mit @capgo/capacitor-zip und laden Sie ein Archiv anstatt hundert Anfragen.

Webunterstützung

@capacitor/filesystem Arbeitet auf der Webanwendung mit IndexedDB, so dass Ihr code im Browser läuft, wenn Sie entwickeln. Beachten Sie die folgenden Unterschiede: Binärleseoperationen liefern ein BlobDateien leben nur im Browserprofil und die Speichergrenzen sind viel niedriger. Für Webbuilds bevorzugen Sie URL.createObjectURL(blob) für die Anzeige.

Schrittweise Lösung

“Die Datei existiert nicht”Sie haben entweder Verzeichnisse durcheinander gemischt oder einen absoluten Pfad zusammen mit einem directoryverwendet. Wählen Sie entweder einen oder den anderen.

Beschädigte Binärdateien: Sie haben Base64 mit Encoding.UTF8Entfernen Sie die Kodierung.

Das App-Programm stürzt mit großen Dateien ab: Base64 über den Bridge. Verwenden Sie Blöcke, Dateiübertragung oder fetch(convertFileSrc(uri)).

Die Bildanzeige funktioniert nicht auf Android: Sie haben eine file:// Konvertieren Sie es mit Capacitor.convertFileSrc.

Failed to find configured root Beim Teilen auf Android: Die Datei befindet sich außerhalb der Pfade in file_paths.xmlVerwenden Sie den Capgo-Datei-Teiler oder kopieren Sie es Cache first.

Dateien verschwinden auf iOS: sie befanden sich in Cache, die iOS unter Speicherdruck löscht.

App Store-Ablehnung für iCloud-Speicher: große herunterladbare Inhalte in Data oder Documents: große herunterladbare Inhalte in LibraryNoCloud.

oder

Die meisten Dateilogs, wie z.B. die Speicherorte, die Wiederholungsregeln und die Namensgebung, finden Sie in JavaScript und können mit dem Capgo Live-Updates nach der Veröffentlichung. Für die Android-Seite der gemeinsamen Speicherung und der Berechtigungen, fahren Sie mit unserem Leitfaden für die verfügbare Speicherung, und sehen Sie sich an. Datei Picker-Dokumentation Für jede Picker-Option.