Guia de documentação do Tauri 2
Visão geral
O Tauri cria aplicativos desktop e mobile a partir de um núcleo Rust e de um frontend web renderizado pela webview do sistema (WebView2 no Windows, WKWebView no macOS e iOS, WebKitGTK no Linux). Este skill condensa os guias oficiais do Tauri 2 em armadilhas, comportamentos padrão surpreendentes, padrões recomendados e substitutos para o Tauri 1. Cada afirmação abaixo e nos arquivos de referência é seguida pela URL da página de origem, para que possa ser verificada.
Versão coberta
Tauri 2.x, conforme documentado em https://v2.tauri.app/. A documentação não é versionada além da versão principal 2. Onde um recurso requer uma menor específica (por exemplo removeUnusedCommands ou simulação de eventos), o arquivo de referência informa isso. As páginas de referência geradas da API, configuração e CLI não são cobertas: verifique-as no site para obter as assinaturas exatas.
Como navegar
- Leia o início rápido abaixo: ele contém as regras que causam a maioria das falhas.
- Abra apenas o arquivo de referência para a tarefa, a partir da tabela no final.
- Cada arquivo de referência é autocontido e começa com sua lista de conteúdos.
- Para verificar uma afirmação, abra a URL que a segue.
Início rápido: regras e armadilhas
Estrutura do projeto
- O código do aplicativo reside em
src-tauri/src/lib.rssob#[cfg_attr(mobile, tauri::mobile_entry_point)].main.rsapenas chamaapp_lib::run(). https://v2.tauri.app/start/project-structure/ - O Tauri é um host estático: envie saída SSG ou SPA. SSR não funciona. Fixe a porta de desenvolvimento (
strictPort: true) para corresponder abuild.devUrle excluasrc-taurido observador do frontend. https://v2.tauri.app/start/frontend/vite/ - O Windows renderiza com Chromium, macOS e Linux com WebKit: teste ambos os mecanismos. https://v2.tauri.app/start/frontend/vite/
Modelo de segurança
- Cada arquivo em
src-tauri/capabilities/está ativo até queapp.security.capabilitiesliste identificadores. Então apenas os listados se aplicam. https://v2.tauri.app/security/capabilities/ - As capacidades correspondem a rótulos de janela, não a títulos. Uma janela em várias capacidades recebe a união de todas elas. https://v2.tauri.app/security/capabilities/
- Os comandos de plugin são negados até que uma capacidade conceda uma permissão. Uma permissão sem escopo ainda falha:
fs:allow-existssozinha causacaminho proibido. https://v2.tauri.app/learn/security/using-plugin-permissions/ - Os comandos do aplicativo registrados em
invoke_handlersão permitidos para todas as janelas, a menos que sejam declarados através deAppManifest::commandsembuild.rs. https://v2.tauri.app/security/capabilities/ denysempre venceallow. Os curingas ignoram pastas de ponto Unix (requireLiteralLeadingDot). https://v2.tauri.app/security/scope/ https://v2.tauri.app/plugin/file-system/- CSP se aplica apenas quando configurado em
app.security.csp. Prefira o padrão de isolamento para validar IPC. https://v2.tauri.app/security/csp/ https://v2.tauri.app/concept/inter-process-communication/isolation/ - As permissões principais carregam o prefixo
core:.core:defaultas agrupa. https://v2.tauri.app/start/migrate/from-tauri-2-beta/
IPC
- As chaves de argumento JS estão em camelCase (
invokeMessageparainvoke_message). https://v2.tauri.app/develop/calling-rust/ - Apenas a última chamada
invoke_handlerconta: coloque todos os comandos em umgenerate_handler!. https://v2.tauri.app/develop/calling-rust/ - Comandos assíncronos com argumentos emprestados (
&str,State<'_, T>) devem retornar umResult. https://v2.tauri.app/develop/calling-rust/ - Um tipo
State<T>errado compila e falha em tempo de execução comestado não gerenciado para campo .... Não envolva estado emArc. https://v2.tauri.app/develop/state-management/ - Use um
Channelpara streams e dados ordenados. Eventos são JSON sem tipo, lentos para cargas grandes, e eventos direcionados à webview ignoram ouvintes globais. https://v2.tauri.app/develop/calling-frontend/ listenretorna uma Promise da função de remoção do ouvinte: aguarde-a e chame-a ao desmontar. https://v2.tauri.app/develop/_sections/frontend-listen/
Configuração e dependências
- Os arquivos de configuração de plataforma mesclam objetos chave por chave, mas SUBSTITUEM arrays inteiros (
bundle.resources,app.windows). https://v2.tauri.app/develop/configuration-files/ - Mantenha
@tauri-apps/apietaurina mesma versão menor, e cada pacote npm e crate de plugin exatamente na mesma versão. https://v2.tauri.app/develop/updating-dependencies/ - Resolva arquivos empacotados com
resolveResource/BaseDirectory::Resource, nunca manualmente:../se torna_up_. https://v2.tauri.app/develop/resources/
Distribuição
- O atualizador não pode ser executado sem assinatura.
TAURI_SIGNING_PRIVATE_KEYdeve ser uma variável de ambiente real (.envé ignorada),pubkeyé o conteúdo da chave, e perder a chave privada encerra as atualizações para aplicativos instalados. https://v2.tauri.app/plugin/updater/ - Nada verifica atualizações a menos que seu código chame
check(). https://v2.tauri.app/plugin/updater/ - Compile pacotes Linux na distribuição mais antiga que você suporta, ou os usuários encontrarão
GLIBC_x.yy not found. https://v2.tauri.app/distribute/debian/ https://v2.tauri.app/distribute/appimage/ - O macOS fora da App Store precisa de assinatura Developer ID mais notarização. Sem um certificado, assine ad-hoc (
signingIdentity: "-"). https://v2.tauri.app/distribute/sign/macos/ - O recurso
devtoolsusa APIs macOS privadas e bloqueia a revisão da App Store. https://v2.tauri.app/develop/debug/ - Registre instância única primeiro, e sistema de arquivos antes do escopo persistido. https://v2.tauri.app/plugin/single-instance/ https://v2.tauri.app/plugin/persisted-scope/
Migrando do Tauri 1
- Execute
tauri migrate, depois revise: a lista de permissões se torna capacidades etauri::apise torna plugins. https://v2.tauri.app/start/migrate/from-tauri-1/ - As importações mudam de
@tauri-apps/api/tauripara@tauri-apps/api/core. https://v2.tauri.app/start/migrate/from-tauri-1/ - No Windows, a origem muda de
https://tauri.localhostparahttp://, o que redefine LocalStorage e IndexedDB a menos queuseHttpsScheme: trueesteja configurado. https://v2.tauri.app/start/migrate/from-tauri-1/
Arquivos de referência
| Arquivo | Leia quando |
|---|---|
| references/getting-started.md | Instalando pré-requisitos, scaffolding, configurando Vite/Next/Nuxt/SvelteKit/Trunk, executando tauri dev no desktop ou em um dispositivo móvel |
| references/migration-from-v1.md | Atualizando um aplicativo Tauri 1 ou 2.0 beta: movimentos de chaves de configuração, recursos removidos, APIs renomeadas e variáveis de ambiente |
| references/security-capabilities.md | Escrevendo capacidades, permissões, conjuntos de permissões ou escopos, ou depurando um erro "não permitido" |
| references/security-csp-isolation.md | Configurando CSP, o padrão de isolamento, o escopo do protocolo de ativos, cabeçalhos de resposta ou endurecendo a cadeia de compilação |
| references/ipc-commands-and-state.md | Definindo comandos, argumentos, erros, comandos assíncronos, parâmetros injetados e estado gerenciado |
| references/ipc-events-and-channels.md | Emitindo e ouvindo eventos, transmitindo com canais, avaliando JS a partir do Rust |
| references/configuration-and-resources.md | Formatos de configuração e mesclagens de plataforma, variantes de compilação, sincronização de versão, ícones, recursos empacotados, tamanho do binário |
| references/plugins-files-network-data.md | Instalando qualquer plugin oficial e usando 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 e plugins de dispositivo móvel |
| references/plugin-authoring.md | Escrevendo um plugin: nomenclatura, configuração, hooks, permissões de comando, escopos, código Kotlin e Swift |
| references/debugging.md | Código somente em desenvolvimento, devtools em release, depuração IDE, janela em branco no Linux ou problemas com WebGL |
| references/testing.md | Simulando IPC em testes unitários, testes de ponta a ponta com WebDriver, executando-os no CI |
| references/distribute-linux.md | Compilando pacotes deb, rpm, AppImage, Flatpak, Snap ou AUR e compilações ARM Linux |
| references/distribute-windows-macos.md | Instaladores MSI/NSIS Windows, modos de instalação WebView2, pacote de aplicativos macOS e DMG |
| references/distribute-mobile-and-stores.md | Assinatura Android e Google Play, assinatura iOS, App Store para iOS e macOS, Microsoft Store |
| references/code-signing-desktop.md | Assinando e notarizando no macOS, assinando no Windows com um certificado ou signCommand |
| references/updater-and-ci.md | Configurando o atualizador, manifestos e canais de atualização e o fluxo de trabalho de lançamento tauri-action |
| references/recipes-windows-tray-menu.md | Rótulos de janela, barras de título personalizadas, bandeja do sistema, menus de janela e aplicativo |
| references/recipes-sidecar-splash-mobile.md | Binários sidecar, um sidecar Node.js, telas de inicialização, associações de arquivo, múltiplas janelas no mobile |
Fontes e detalhes de busca: SOURCES.md.