Guide de documentation Tauri 2
Vue d'ensemble
Tauri permet de créer des applications de bureau et mobiles à partir d'un noyau Rust et d'un frontend web rendu par le webview système (WebView2 sur Windows, WKWebView sur macOS et iOS, WebKitGTK sur Linux). Ce skill condense les guides officiels de Tauri 2 en pièges, valeurs par défaut surprenantes, motifs recommandés et remplacements pour Tauri 1. Chaque affirmation ci-dessous et dans les fichiers de référence se termine par l'URL de la page dont elle provient, afin de pouvoir être vérifiée.
Version couverte
Tauri 2.x, tel que documenté sur https://v2.tauri.app/. La documentation n'est pas versionnée au-delà de la version majeure 2. Lorsqu'une fonctionnalité nécessite une version mineure spécifique (par exemple removeUnusedCommands ou le mock d'événements), le fichier de référence le mentionne. Les pages de référence générées pour l'API, la configuration et la CLI ne sont pas couvertes : consultez le site pour les signatures exactes.
Comment naviguer
- Lisez le guide de démarrage rapide ci-dessous : il contient les règles qui causent le plus d'échecs.
- Ouvrez uniquement le fichier de référence correspondant à la tâche, depuis le tableau à la fin.
- Chaque fichier de référence est autonome et commence par sa table des matières.
- Pour vérifier une affirmation, ouvrez l'URL qui la suit.
Guide de démarrage rapide : règles et pièges
Structure du projet
- Le code de l'application se trouve dans
src-tauri/src/lib.rssous#[cfg_attr(mobile, tauri::mobile_entry_point)].main.rsappelle uniquementapp_lib::run(). https://v2.tauri.app/start/project-structure/ - Tauri est un hôte statique : livrez la sortie SSG ou SPA. Le SSR ne s'exécute pas. Fixez le port de développement (
strictPort: true) pour correspondre àbuild.devUrl, et excluezsrc-tauridu watcher frontend. https://v2.tauri.app/start/frontend/vite/ - Windows utilise Chromium, macOS et Linux utilisent WebKit : testez les deux moteurs. https://v2.tauri.app/start/frontend/vite/
Modèle de sécurité
- Chaque fichier dans
src-tauri/capabilities/est actif jusqu'à ce queapp.security.capabilitiesliste des identifiants. Ensuite, seuls ceux listés s'appliquent. https://v2.tauri.app/security/capabilities/ - Les capacités correspondent aux étiquettes de fenêtre, pas aux titres. Une fenêtre dans plusieurs capacités obtient l'union de toutes ces capacités. https://v2.tauri.app/security/capabilities/
- Les commandes de plugin sont refusées jusqu'à ce qu'une capacité accorde une permission. Une permission sans portée échoue toujours :
fs:allow-existsseul donneforbidden path. https://v2.tauri.app/learn/security/using-plugin-permissions/ - Les commandes d'application enregistrées dans
invoke_handlersont autorisées pour chaque fenêtre, sauf si elles sont déclarées viaAppManifest::commandsdansbuild.rs. https://v2.tauri.app/security/capabilities/ denyl'emporte toujours surallow. Les caractères génériques ignorent les dossiers point de type Unix (requireLiteralLeadingDot). https://v2.tauri.app/security/scope/ https://v2.tauri.app/plugin/file-system/- CSP s'applique uniquement lorsqu'il est défini dans
app.security.csp. Préférez le pattern d'isolation pour valider l'IPC. https://v2.tauri.app/security/csp/ https://v2.tauri.app/concept/inter-process-communication/isolation/ - Les permissions du noyau portent le préfixe
core:.core:defaultles regroupe. https://v2.tauri.app/start/migrate/from-tauri-2-beta/
IPC
- Les clés d'arguments JS sont en camelCase (
invokeMessagepourinvoke_message). https://v2.tauri.app/develop/calling-rust/ - Seul le dernier appel à
invoke_handlercompte : placez chaque commande dans un seulgenerate_handler!. https://v2.tauri.app/develop/calling-rust/ - Les commandes asynchrones avec des arguments empruntés (
&str,State<'_, T>) doivent retourner unResult. https://v2.tauri.app/develop/calling-rust/ - Un mauvais type
State<T>se compile et échoue à l'exécution avecstate not managed for field .... N'enveloppez pas l'état dansArc. https://v2.tauri.app/develop/state-management/ - Utilisez un
Channelpour les flux et les données ordonnées. Les événements sont du JSON non typé, lents pour de grandes charges utiles, et les événements ciblant le webview ignorent les écouteurs globaux. https://v2.tauri.app/develop/calling-frontend/ listenretourne une Promesse de la fonction de désabonnement : attendez-la et appelez-la lors du démontage. https://v2.tauri.app/develop/_sections/frontend-listen/
Configuration et dépendances
- Les fichiers de configuration de plateforme fusionnent les objets clé par clé mais REMPLACENT les tableaux entiers (
bundle.resources,app.windows). https://v2.tauri.app/develop/configuration-files/ - Gardez
@tauri-apps/apiettaurisur la même version mineure, et chaque package npm et crate du plugin sur la version exactement identique. https://v2.tauri.app/develop/updating-dependencies/ - Résolvez les fichiers groupés avec
resolveResource/BaseDirectory::Resource, jamais manuellement :../devient_up_. https://v2.tauri.app/develop/resources/
Livraison
- Le mécanisme de mise à jour ne peut pas s'exécuter sans signature.
TAURI_SIGNING_PRIVATE_KEYdoit être une variable d'environnement réelle (.envest ignoré),pubkeyest le contenu de la clé, et perdre la clé privée met fin aux mises à jour pour les applications installées. https://v2.tauri.app/plugin/updater/ - Rien ne vérifie les mises à jour sauf si votre code appelle
check(). https://v2.tauri.app/plugin/updater/ - Construisez les paquets Linux sur la distribution la plus ancienne que vous supportez, sinon les utilisateurs rencontreront
GLIBC_x.yy not found. https://v2.tauri.app/distribute/debian/ https://v2.tauri.app/distribute/appimage/ - macOS en dehors de l'App Store nécessite une signature Developer ID plus une notarisation. Sans certificat, signez ad-hoc (
signingIdentity: "-"). https://v2.tauri.app/distribute/sign/macos/ - La fonctionnalité
devtoolsutilise des API macOS privées et bloque la revue de l'App Store. https://v2.tauri.app/develop/debug/ - Enregistrez d'abord l'instance unique, puis le système de fichiers avant la portée persistée. https://v2.tauri.app/plugin/single-instance/ https://v2.tauri.app/plugin/persisted-scope/
Migration depuis Tauri 1
- Exécutez
tauri migrate, puis révisez : la liste d'autorisation devient des capacités ettauri::apidevient des plugins. https://v2.tauri.app/start/migrate/from-tauri-1/ - Les imports passent de
@tauri-apps/api/taurià@tauri-apps/api/core. https://v2.tauri.app/start/migrate/from-tauri-1/ - Sur Windows, l'origine passe de
https://tauri.localhostàhttp://, ce qui réinitialise LocalStorage et IndexedDB sauf siuseHttpsScheme: trueest défini. https://v2.tauri.app/start/migrate/from-tauri-1/
Fichiers de référence
| Fichier | Lire quand |
|---|---|
| references/getting-started.md | Installer les prérequis, structurer le projet, configurer Vite/Next/Nuxt/SvelteKit/Trunk, exécuter tauri dev sur ordinateur ou appareil mobile |
| references/migration-from-v1.md | Mettre à jour une application Tauri 1 ou 2.0 beta : déplacements de clés de configuration, fonctionnalités supprimées, API et variables d'environnement renommées |
| references/security-capabilities.md | Écrire des capacités, des permissions, des ensembles de permissions ou des portées, ou déboguer une erreur "not allowed" |
| references/security-csp-isolation.md | Définir CSP, le pattern d'isolation, la portée du protocole des assets, les en-têtes de réponse, ou renforcer la chaîne de construction |
| references/ipc-commands-and-state.md | Définir des commandes, des arguments, des erreurs, des commandes asynchrones, des paramètres injectés et l'état géré |
| references/ipc-events-and-channels.md | Émettre et écouter des événements, diffuser avec des canaux, évaluer du JS depuis Rust |
| references/configuration-and-resources.md | Formats de configuration et fusions de plateformes, variantes de construction, synchronisation des versions, icônes, ressources groupées, taille du binaire |
| references/plugins-files-network-data.md | Installer n'importe quel plugin officiel, et utiliser fs, dialog, opener, shell, http, upload, websocket, sql, store, stronghold ou log |
| references/plugins-app-and-mobile.md | single-instance, deep-link, autostart, cli, global-shortcut, window-state, positioner, notification, et les plugins pour appareils mobiles |
| references/plugin-authoring.md | Écrire un plugin : nommage, configuration, hooks, permissions des commandes, portées, code Kotlin et Swift |
| references/debugging.md | Code réservé au développement, outils de développement en release, débogage IDE, fenêtre blanche Linux ou problèmes WebGL |
| references/testing.md | Simuler l'IPC dans les tests unitaires, tests de bout en bout WebDriver, exécution dans CI |
| references/distribute-linux.md | Construire des paquets deb, rpm, AppImage, Flatpak, Snap ou AUR, et constructions ARM Linux |
| references/distribute-windows-macos.md | Installateurs Windows MSI/NSIS, modes d'installation WebView2, bundle d'application macOS et DMG |
| references/distribute-mobile-and-stores.md | Signature Android et Google Play, signature iOS, App Store pour iOS et macOS, Microsoft Store |
| references/code-signing-desktop.md | Signature et notarisation sur macOS, signature sur Windows avec un certificat ou signCommand |
| references/updater-and-ci.md | Configurer le mécanisme de mise à jour, les manifestes et canaux de mise à jour, et le workflow de release tauri-action |
| references/recipes-windows-tray-menu.md | Étiquettes de fenêtre, barres de titre personnalisées, barre système, menus de fenêtre et d'application |
| references/recipes-sidecar-splash-mobile.md | Binaires sidecar, sidecar Node.js, écrans de démarrage, associations de fichiers, fenêtres multiples sur mobile |
Sources et détails de récupération : SOURCES.md.