Tauri 2 Dokumentationsleitfaden
Überblick
Tauri erstellt Desktop- und Mobile-Apps aus einem Rust-Kern und einem Web-Frontend, das vom systemeigenen Webview gerendert wird (WebView2 unter Windows, WKWebView unter macOS und iOS, WebKitGTK unter Linux). Diese Skill-Anleitung verdichtet die offiziellen Tauri 2-Leitfäden zu Fallstricken, überraschenden Voreinstellungen, empfohlenen Mustern und Ersetzungen für Tauri 1. Jede Behauptung unten und in den Referenzdateien endet mit der URL der Seite, von der sie stammt, sodass sie überprüft werden kann.
Abgedeckte Version
Tauri 2.x, dokumentiert unter https://v2.tauri.app/. Die Dokumentation ist außerhalb von Major 2 nicht versioniert. Wo eine Funktion eine bestimmte Minor-Version benötigt (z. B. removeUnusedCommands oder Event-Mocking), gibt die Referenzdatei dies an. Generierte API-, Konfigurations- und CLI-Referenzseiten werden nicht abgedeckt: Überprüfen Sie diese auf der Website für genaue Signaturen.
So navigieren Sie
- Lesen Sie den untenstehenden Schnellstart: Er enthält die Regeln, die die meisten Fehler verursachen.
- Öffnen Sie nur die Referenzdatei für die Aufgabe aus der Tabelle am Ende.
- Jede Referenzdatei ist in sich abgeschlossen und beginnt mit ihrer Inhaltsliste.
- Um eine Behauptung zu überprüfen, öffnen Sie die URL, die ihr folgt.
Schnellstart: Regeln und Fallstricke
Projektstruktur
- Der App-Code lebt in
src-tauri/src/lib.rsunter#[cfg_attr(mobile, tauri::mobile_entry_point)].main.rsruft nurapp_lib::run()auf. https://v2.tauri.app/start/project-structure/ - Tauri ist ein statischer Host: Liefern Sie SSG- oder SPA-Output aus. SSR läuft nicht. Fixieren Sie den Dev-Port (
strictPort: true), damit er zubuild.devUrlpasst, und schließen Siesrc-taurivom Frontend-Watcher aus. https://v2.tauri.app/start/frontend/vite/ - Windows rendert mit Chromium, macOS und Linux mit WebKit: Testen Sie beide Engines. https://v2.tauri.app/start/frontend/vite/
Sicherheitsmodell
- Jede Datei in
src-tauri/capabilities/ist aktiv, bisapp.security.capabilitiesBezeichner auflistet. Dann gelten nur die aufgelisteten. https://v2.tauri.app/security/capabilities/ - Capabilities gleichen Fenster-Labeln ab, nicht Titeln. Ein Fenster in mehreren Capabilities erhält die Vereinigung aller. https://v2.tauri.app/security/capabilities/
- Plugin-Befehle sind verweigert, bis eine Capability eine Berechtigung erteilt. Eine Berechtigung ohne Scope schlägt dennoch fehl:
fs:allow-existsallein führt zu „forbidden path“. https://v2.tauri.app/learn/security/using-plugin-permissions/ - App-Befehle, die in
invoke_handlerregistriert sind, sind für jedes Fenster erlaubt, sofern sie nicht überAppManifest::commandsinbuild.rsdeklariert wurden. https://v2.tauri.app/security/capabilities/ denygewinnt immer überallow. Platzhalter überspringen Unix-Punkt-Ordner (requireLiteralLeadingDot). https://v2.tauri.app/security/scope/ https://v2.tauri.app/plugin/file-system/- CSP gilt nur, wenn es in
app.security.cspgesetzt ist. Bevorzugen Sie das Isolation Pattern zur Validierung von IPC. https://v2.tauri.app/security/csp/ https://v2.tauri.app/concept/inter-process-communication/isolation/ - Kernberechtigungen tragen das Präfix
core:.core:defaultbündelt sie. https://v2.tauri.app/start/migrate/from-tauri-2-beta/
IPC
- JS-Argumentschlüssel sind camelCase (
invokeMessagefürinvoke_message). https://v2.tauri.app/develop/calling-rust/ - Nur der letzte
invoke_handler-Aufruf zählt: Setzen Sie jeden Befehl in eingenerate_handler!. https://v2.tauri.app/develop/calling-rust/ - Asynchrone Befehle mit geliehenen Argumenten (
&str,State<'_, T>) müssen einResultzurückgeben. https://v2.tauri.app/develop/calling-rust/ - Ein falscher
State<T>-Typ kompiliert und schlägt zur Laufzeit mit „state not managed for field ...“ fehl. Wickeln Sie State nicht inArc. https://v2.tauri.app/develop/state-management/ - Verwenden Sie einen
Channelfür Streams und geordnete Daten. Events sind untypisiertes JSON, langsam für große Nutzlasten, und an Webview gerichtete Events überspringen globale Listener. https://v2.tauri.app/develop/calling-frontend/ listengibt ein Promise der Unlisten-Funktion zurück: Warten Sie darauf und rufen Sie es beim Unmount auf. https://v2.tauri.app/develop/_sections/frontend-listen/
Konfiguration und Abhängigkeiten
- Plattform-Konfigurationsdateien führen Objekte Schlüssel für Schlüssel zusammen, ersetzen aber ARRAYS vollständig (
bundle.resources,app.windows). https://v2.tauri.app/develop/configuration-files/ - Halten Sie
@tauri-apps/apiundtauriauf derselben Minor-Version sowie jedes Plugin-NPM-Paket und die zugehörige Crate auf exakt derselben Version. https://v2.tauri.app/develop/updating-dependencies/ - Lösen Sie gebündelte Dateien mit
resolveResource/BaseDirectory::Resourceauf, niemals manuell:../wird zu_up_. https://v2.tauri.app/develop/resources/
Auslieferung
- Der Updater kann nicht ohne Signierung ausgeführt werden.
TAURI_SIGNING_PRIVATE_KEYmuss eine echte Umgebungsvariable sein (.envwird ignoriert),pubkeyist der Schlüsselinhalt, und der Verlust des privaten Schlüssels beendet Updates für installierte Apps. https://v2.tauri.app/plugin/updater/ - Nichts prüft auf Updates, es sei denn, Ihr Code ruft
check()auf. https://v2.tauri.app/plugin/updater/ - Bauen Sie Linux-Pakete auf der ältesten Distribution, die Sie unterstützen, sonst erhalten Benutzer „GLIBC_x.yy not found“. https://v2.tauri.app/distribute/debian/ https://v2.tauri.app/distribute/appimage/
- macOS außerhalb des App Store benötigt Developer-ID-Signierung plus Notarisierung. Ohne Zertifikat ad-hoc signieren (
signingIdentity: "-"). https://v2.tauri.app/distribute/sign/macos/ - Die
devtools-Funktion verwendet private macOS-APIs und blockiert die App-Store-Überprüfung. https://v2.tauri.app/develop/debug/ - Registrieren Sie Single-Instance zuerst und fs vor persisted-scope. https://v2.tauri.app/plugin/single-instance/ https://v2.tauri.app/plugin/persisted-scope/
Migration von Tauri 1
- Führen Sie
tauri migrateaus, dann überprüfen: Die Allowlist wird zu Capabilities undtauri::apiwird zu Plugins. https://v2.tauri.app/start/migrate/from-tauri-1/ - Importe verschieben sich von
@tauri-apps/api/taurizu@tauri-apps/api/core. https://v2.tauri.app/start/migrate/from-tauri-1/ - Unter Windows wechselt der Ursprung von
https://tauri.localhostzuhttp://, was LocalStorage und IndexedDB zurücksetzt, es sei denn,useHttpsScheme: trueist gesetzt. https://v2.tauri.app/start/migrate/from-tauri-1/
Referenzdateien
| Datei | Lesen Sie, wenn |
|---|---|
| references/getting-started.md | Voraussetzungen installieren, Gerüst bauen, Vite/Next/Nuxt/SvelteKit/Trunk verdrahten, tauri dev auf dem Desktop oder einem mobilen Gerät ausführen |
| references/migration-from-v1.md | Aktualisieren einer Tauri 1- oder 2.0-Beta-App: Konfigurationsschlüsselverschiebungen, entfernte Funktionen, umbenannte APIs und Umgebungsvariablen |
| references/security-capabilities.md | Schreiben von Capabilities, Berechtigungen, Berechtigungssätzen oder Scopes oder Debuggen eines „nicht erlaubt“-Fehlers |
| references/security-csp-isolation.md | CSP setzen, das Isolation Pattern, den Asset-Protocol-Scope, Antwort-Header oder Härten der Build-Kette |
| references/ipc-commands-and-state.md | Definieren von Befehlen, Argumenten, Fehlern, asynchronen Befehlen, injizierten Parametern und verwaltetem Zustand |
| references/ipc-events-and-channels.md | Senden und Empfangen von Events, Streamen mit Channels, Auswerten von JS aus Rust |
| references/configuration-and-resources.md | Konfigurationsformate und Plattform-Merges, Build-Varianten, Versionssynchronisation, Icons, gebündelte Ressourcen, Binärgröße |
| references/plugins-files-network-data.md | Installieren jedes offiziellen Plugins und Verwenden von fs, dialog, opener, shell, http, upload, websocket, sql, store, stronghold oder log |
| references/plugins-app-and-mobile.md | single-instance, deep-link, autostart, cli, global-shortcut, window-state, positioner, notification und mobile Geräte-Plugins |
| references/plugin-authoring.md | Schreiben eines Plugins: Benennung, Konfiguration, Hooks, Befehlsberechtigungen, Scopes, Kotlin- und Swift-Code |
| references/debugging.md | Nur-Dev-Code, Devtools im Release, IDE-Debugging, leeres Linux-Fenster oder WebGL-Probleme |
| references/testing.md | Mocking von IPC in Unit-Tests, WebDriver-End-to-End-Tests, Ausführen in CI |
| references/distribute-linux.md | Erstellen von deb-, rpm-, AppImage-, Flatpak-, Snap- oder AUR-Paketen und ARM-Linux-Builds |
| references/distribute-windows-macos.md | Windows-MSI/NSIS-Installer, WebView2-Installationsmodi, macOS-App-Bundle und DMG |
| references/distribute-mobile-and-stores.md | Android-Signierung und Google Play, iOS-Signierung, App Store für iOS und macOS, Microsoft Store |
| references/code-signing-desktop.md | Signieren und Notarisieren unter macOS, Signieren unter Windows mit einem Zertifikat oder signCommand |
| references/updater-and-ci.md | Einrichten des Updaters, Update-Manifeste und -Kanäle und den tauri-action-Release-Workflow |
| references/recipes-windows-tray-menu.md | Fenster-Label, benutzerdefinierte Titelleisten, Systray, Fenster- und App-Menüs |
| references/recipes-sidecar-splash-mobile.md | Sidecar-Binärdateien, ein Node.js-Sidecar, Splashscreens, Dateizuordnungen, Multi-Window auf Mobilgeräten |
Quellen und Abrufdetails: SOURCES.md.