Guía de documentación de Tauri 2
Resumen
Tauri crea aplicaciones de escritorio y móviles a partir de un núcleo en Rust y un frontend web renderizado por el webview del sistema (WebView2 en Windows, WKWebView en macOS e iOS, WebKitGTK en Linux). Esta habilidad condensa las guías oficiales de Tauri 2 en puntos críticos, defaults sorprendentes, patrones recomendados y sustitutos de Tauri 1. Cada afirmación a continuación y en los archivos de referencia termina con la URL de la página de la que proviene, para que pueda ser verificada.
Versión cubierta
Tauri 2.x, según se documenta en https://v2.tauri.app/. Los docs no tienen versiones más allá de la mayor 2. Cuando una característica necesita una versión menor específica (por ejemplo removeUnusedCommands o el mock de eventos), el archivo de referencia lo indica. Las páginas de referencia de API, configuración y CLI generadas no están cubiertas: consúltelas en el sitio para obtener firmas exactas.
Cómo navegar
- Lea la guía rápida a continuación: contiene las reglas que causan la mayoría de los fallos.
- Abra solo el archivo de referencia para la tarea, de la tabla al final.
- Cada archivo de referencia es autocontenido y comienza con su lista de contenidos.
- Para verificar una afirmación, abra la URL que la sigue.
Guía rápida: reglas y puntos críticos
Estructura del proyecto
- El código de la aplicación vive en
src-tauri/src/lib.rsbajo#[cfg_attr(mobile, tauri::mobile_entry_point)].main.rssolo llama aapp_lib::run(). https://v2.tauri.app/start/project-structure/ - Tauri es un host estático: sirva salida SSG o SPA. SSR no se ejecuta. Fije el puerto de desarrollo (
strictPort: true) para que coincida conbuild.devUrl, y excluyasrc-tauridel watcher del frontend. https://v2.tauri.app/start/frontend/vite/ - Windows renderiza con Chromium, macOS y Linux con WebKit: pruebe ambos motores. https://v2.tauri.app/start/frontend/vite/
Modelo de seguridad
- Cada archivo en
src-tauri/capabilities/está activo hasta queapp.security.capabilitieslista identificadores. Entonces solo se aplican los listados. https://v2.tauri.app/security/capabilities/ - Las capacidades coinciden con etiquetas de ventana, no con títulos. Una ventana en varias capacidades obtiene la unión de todas ellas. https://v2.tauri.app/security/capabilities/
- Los comandos de plugins están denegados hasta que una capacidad concede un permiso. Un permiso sin ámbito todavía falla:
fs:allow-existssolo daforbidden path. https://v2.tauri.app/learn/security/using-plugin-permissions/ - Los comandos de la aplicación registrados en
invoke_handlerse permiten para cada ventana a menos que se declaren a través deAppManifest::commandsenbuild.rs. https://v2.tauri.app/security/capabilities/ denysiempre gana sobreallow. Los comodines omiten las carpetas con punto de Unix (requireLiteralLeadingDot). https://v2.tauri.app/security/scope/ https://v2.tauri.app/plugin/file-system/- CSP se aplica solo cuando se establece en
app.security.csp. Prefiera el patrón de aislamiento para validar IPC. https://v2.tauri.app/security/csp/ https://v2.tauri.app/concept/inter-process-communication/isolation/ - Los permisos principales llevan el prefijo
core:.core:defaultlos agrupa. https://v2.tauri.app/start/migrate/from-tauri-2-beta/
IPC
- Las claves de los argumentos JS son camelCase (
invokeMessageparainvoke_message). https://v2.tauri.app/develop/calling-rust/ - Solo cuenta la última llamada a
invoke_handler: ponga cada comando en un sologenerate_handler!. https://v2.tauri.app/develop/calling-rust/ - Los comandos asíncronos con argumentos prestados (
&str,State<'_, T>) deben devolver unResult. https://v2.tauri.app/develop/calling-rust/ - Un tipo
State<T>incorrecto compila y falla en tiempo de ejecución constate not managed for field .... No envuelva el estado enArc. https://v2.tauri.app/develop/state-management/ - Use un
Channelpara streams y datos ordenados. Los eventos son JSON sin tipo, lentos para cargas grandes, y los eventos dirigidos al webview omiten los listeners globales. https://v2.tauri.app/develop/calling-frontend/ listendevuelve una Promise de la función unlisten: espérela y llámela al desmontar. https://v2.tauri.app/develop/_sections/frontend-listen/
Configuración y dependencias
- Los archivos de configuración de plataforma fusionan objetos clave por clave pero REEMPLAZAN los arrays completos (
bundle.resources,app.windows). https://v2.tauri.app/develop/configuration-files/ - Mantenga
@tauri-apps/apiytaurien la misma versión menor, y el paquete npm y la crate de cada plugin en la misma versión exacta. https://v2.tauri.app/develop/updating-dependencies/ - Resuelva los archivos empaquetados con
resolveResource/BaseDirectory::Resource, nunca a mano:../se convierte en_up_. https://v2.tauri.app/develop/resources/
Distribución
- El actualizador no puede ejecutarse sin firmar.
TAURI_SIGNING_PRIVATE_KEYdebe ser una variable de entorno real (.envse ignora),pubkeyes el contenido de la clave, y perder la clave privada termina las actualizaciones para las aplicaciones instaladas. https://v2.tauri.app/plugin/updater/ - Nada comprueba actualizaciones a menos que su código llame a
check(). https://v2.tauri.app/plugin/updater/ - Construya paquetes Linux en la distribución más antigua que soporte, o los usuarios encontrarán
GLIBC_x.yy not found. https://v2.tauri.app/distribute/debian/ https://v2.tauri.app/distribute/appimage/ - macOS fuera de la App Store necesita firma Developer ID más notarización. Sin certificado, firme ad-hoc (
signingIdentity: "-"). https://v2.tauri.app/distribute/sign/macos/ - La característica
devtoolsusa APIs privadas de macOS y bloquea la revisión de la App Store. https://v2.tauri.app/develop/debug/ - Registre single-instance primero, y fs antes que persisted-scope. https://v2.tauri.app/plugin/single-instance/ https://v2.tauri.app/plugin/persisted-scope/
Migración desde Tauri 1
- Ejecute
tauri migrate, luego revise: la allowlist se convierte en capacidades ytauri::apise convierte en plugins. https://v2.tauri.app/start/migrate/from-tauri-1/ - Las importaciones se mueven de
@tauri-apps/api/tauria@tauri-apps/api/core. https://v2.tauri.app/start/migrate/from-tauri-1/ - En Windows el origen se mueve de
https://tauri.localhostahttp://, lo que reinicia LocalStorage e IndexedDB a menos que se establezcauseHttpsScheme: true. https://v2.tauri.app/start/migrate/from-tauri-1/
Archivos de referencia
| Archivo | Leer cuando |
|---|---|
| references/getting-started.md | Instalar requisitos previos, scaffolding, conectar Vite/Next/Nuxt/SvelteKit/Trunk, ejecutar tauri dev en escritorio o dispositivo móvil |
| references/migration-from-v1.md | Actualizar una app Tauri 1 o 2.0 beta: movimientos de claves de configuración, características eliminadas, APIs renombradas y variables de entorno |
| references/security-capabilities.md | Escribir capacidades, permisos, conjuntos de permisos o ámbitos, o depurar un error "not allowed" |
| references/security-csp-isolation.md | Establecer CSP, el patrón de aislamiento, el ámbito del protocolo de assets, encabezados de respuesta, o endurecer la cadena de compilación |
| references/ipc-commands-and-state.md | Definir comandos, argumentos, errores, comandos asíncronos, parámetros inyectados y estado gestionado |
| references/ipc-events-and-channels.md | Emitir y escuchar eventos, hacer streaming con channels, evaluar JS desde Rust |
| references/configuration-and-resources.md | Formatos de configuración y fusiones de plataforma, variantes de compilación, sincronización de versiones, iconos, recursos empaquetados, tamaño del binario |
| references/plugins-files-network-data.md | Instalar cualquier plugin oficial, y usar fs, dialog, opener, shell, http, upload, websocket, sql, store, stronghold o log |
| references/plugins-app-and-mobile.md | single-instance, deep-link, autostart, cli, global-shortcut, window-state, positioner, notification, y plugins para dispositivos móviles |
| references/plugin-authoring.md | Escribir un plugin: nombre, configuración, hooks, permisos de comandos, ámbitos, código Kotlin y Swift |
| references/debugging.md | Código solo para desarrollo, devtools en release, depuración en IDE, ventana en blanco en Linux o problemas con WebGL |
| references/testing.md | Mockear IPC en tests unitarios, tests end-to-end con WebDriver, ejecutarlos en CI |
| references/distribute-linux.md | Construir paquetes deb, rpm, AppImage, Flatpak, Snap o AUR, y compilaciones ARM Linux |
| references/distribute-windows-macos.md | Instaladores MSI/NSIS en Windows, modos de instalación de WebView2, paquete de aplicación macOS y DMG |
| references/distribute-mobile-and-stores.md | Firma de Android y Google Play, firma de iOS, App Store para iOS y macOS, Microsoft Store |
| references/code-signing-desktop.md | Firmar y notarizar en macOS, firmar en Windows con un certificado o signCommand |
| references/updater-and-ci.md | Configurar el actualizador, manifiestos de actualización y canales, y el flujo de trabajo de release tauri-action |
| references/recipes-windows-tray-menu.md | Etiquetas de ventana, barras de título personalizadas, bandeja del sistema, menús de ventana y aplicación |
| references/recipes-sidecar-splash-mobile.md | Binarios sidecar, un sidecar Node.js, splashscreens, asociaciones de archivos, múltiples ventanas en móvil |
Fuentes y detalles de obtención: SOURCES.md.