Aplicativo Wails com atualização automática

Gere a estrutura de um novo projeto com o modelo vanilla:

wails3 init -n updater-tutorial -t vanilla
cd updater-tutorial

Agora você deve ter um diretório com main.go, frontend/ e um Taskfile.yml. Confirme que ele é compilado e iniciado:

wails3 task dev

Uma janela vazia do Wails deve ser aberta. Feche-a e continue.

Abra main.go e adicione os dois pacotes do atualizador às importações:

package main

import (
    _ "embed"

    "github.com/wailsapp/wails/v3/pkg/application"
    "github.com/wailsapp/wails/v3/pkg/updater"
    "github.com/wailsapp/wails/v3/pkg/updater/providers/github"
)

Esses pacotes importam o próprio Updater e o provedor do GitHub Releases.

app.Updater já está integrado a cada *application.App — basta chamar Init:

const currentVersion = "1.0.0"

gh, err := github.New(github.Config{
    Repository:    "yourorg/your-repo",   // ← change this
    ChecksumAsset: "SHA256SUMS",          // sibling file with sha256 digests
})
if err != nil {
    log.Fatalf("github.New: %v", err)
}

if err := app.Updater.Init(updater.Config{
    CurrentVersion: currentVersion,
    Providers:      []updater.Provider{gh},
}); err != nil {
    log.Fatalf("Updater.Init: %v", err)
}

Coloque isto depois de application.New e antes de app.Run().

No mesmo main.go, adicione uma entrada de menu “Verificar atualizações…”:

menu := app.Menu.New()
app.Menu.SetApplicationMenu(menu)
appMenu := menu.AddSubmenu("App")
appMenu.Add("Check for Updates…").OnClick(func(*application.Context) {
    go func() {
        if err := app.Updater.CheckAndInstall(context.Background()); err != nil {
            app.Logger.Error("update", "error", err)
        }
    }()
})

CheckAndInstall abre a janela de atualização do framework, executa Check e, se encontrar uma versão, executa DownloadAndInstall automaticamente. Quando não há novidades, a janela permanece aberta no estado “Atualizado” — o usuário a fecha com o botão Fechar.

wails3 task dev

Clique em Aplicativo → Verificar atualizações…. A janela de atualização deve abrir brevemente, consultar a API do GitHub, não encontrar versões mais recentes que 1.0.0 e permanecer no estado Atualizado, com um ✓ verde.

Se ocorrer um erro aqui, geralmente será um destes:

Atualize currentVersion em main.go para 1.0.0 (ou deixe como está). Compile para uma plataforma a fim de obter um binário que você possa anexar a uma versão:

wails3 task build:darwin
# produces bin/updater-tutorial.app
# zip it for the release asset:
cd bin && zip -r updater-tutorial-darwin-arm64.zip updater-tutorial.app && cd ..

wails3 task build:linux
# produces bin/updater-tutorial
mv bin/updater-tutorial bin/updater-tutorial-linux-amd64

wails3 task build:windows
# produces bin/updater-tutorial.exe
mv bin/updater-tutorial.exe bin/updater-tutorial-windows-amd64.exe

Gere um arquivo SHA256SUMS ao lado do binário:

cd bin
shasum -a 256 updater-tutorial-* > SHA256SUMS
cat SHA256SUMS

Você deve ver uma ou mais linhas como esta:

abc123…  updater-tutorial-darwin-arm64.zip

Agora publique isso como v2.0.0 no seu repositório do GitHub:

gh release create v2.0.0 \
    --title "v2.0.0" \
    --notes "First update for the self-update tutorial.

- **Bold** Markdown renders in the update window
- \`Code spans\` too
- Lists work
- GFM tables work" \
    bin/SHA256SUMS bin/updater-tutorial-*

Com currentVersion ainda definido como 1.0.0, execute o aplicativo novamente:

wails3 task dev

Clique em Aplicativo → Verificar atualizações…. Desta vez, você deve ver algo assim:

• O ícone principal muda de ↓ azul (“Atualização disponível”) para ✓ verde (“Atualização pronta”).
• O subtítulo mostra v1.0.0 → v2.0.0 · <size>.
• O painel de notas da versão renderiza o Markdown com negrito, trechos de código e a tabela.
• A barra de progresso é preenchida durante o download (será rápido — o binário é pequeno).

O Updater prepara o novo binário em um diretório temporário. Para concluir a atualização:

• Clique em Reiniciar e aplicar.
• O aplicativo é encerrado, o auxiliar substitui o binário e o novo binário reinicia.
• O aplicativo reiniciado informa currentVersion = "1.0.0" (porque definimos esse valor diretamente no código), mas os bytes no disco correspondem à compilação v2.0.0.

Em um aplicativo real, currentVersion seria definido no momento da compilação por meio de -ldflags, para que o novo binário saiba que agora é v2.0.0 e uma verificação posterior não encontre nenhuma atualização.

Substitua a constante por uma variável definida no momento da compilação:

var (
    currentVersion = "dev" // overridden by -ldflags at release time
)

Depois, no comando de compilação:

wails3 task build:darwin -- -ldflags "-X main.currentVersion=2.0.0"

Ou adicione -ldflags ao seu Taskfile.yml para que o valor seja obtido de git describe --tags.

O caminho SHA256SUMS verifica a integridade (os bytes correspondem ao que o GitHub armazenou), mas não a autenticidade (se esses bytes foram produzidos pelo seu pipeline de lançamento, e não por meio de uma conta de mantenedor comprometida). Para oferecer resistência à adulteração, assine cada versão com uma chave Ed25519:

# One-time: generate the keypair
ssh-keygen -t ed25519 -f updater-key -N "" -C "wails-updater"
#   updater-key      — keep secret (build server, HSM, password manager)
#   updater-key.pub  — bundle in your app

A cada versão, assine com sua chave privada o resumo SHA-256 de cada artefato. Um pequeno utilitário em Go:

package main

import (
    "crypto/ed25519"
    "crypto/sha256"
    "encoding/base64"
    "fmt"
    "io"
    "os"
)

func main() {
    priv, _ := os.ReadFile("updater-key")
    key := ed25519.PrivateKey(priv) // raw 64-byte private key

    f, _ := os.Open(os.Args[1])
    defer f.Close()
    h := sha256.New()
    _, _ = io.Copy(h, f)
    sig := ed25519.Sign(key, h.Sum(nil))
    fmt.Println(base64.StdEncoding.EncodeToString(sig))
}

No momento, o provedor padrão do GitHub não busca um arquivo de assinatura separado — você pode criar um provedor personalizado que faça isso ou mudar para o keygen.sh, que assina cada artefato no servidor e disponibiliza tanto o resumo quanto a assinatura por meio de sua API.

Incorpore a chave pública ao seu aplicativo:

//go:embed updater-key.pub
var updaterPublicKey []byte

app.Updater.Init(updater.Config{
    CurrentVersion: currentVersion,
    PublicKey:      updaterPublicKey,
    Providers:      []updater.Provider{gh},
})

Com PublicKey definido, qualquer versão que forneça um Signature deve ser validada com essa chave. A origem da versão não tem como substituir a chave por outra — esse é justamente o objetivo de fixá-la por um canal independente durante a compilação.

A janela padrão atende ao caso mais comum. Se precisar de mais controle, há três alternativas — escolha uma conforme o grau de personalização desejado:

app.Updater.Init(updater.Config{
    // …
    Window: &updater.BuiltinWindow{
        CSS: `:root { --accent: #ff6f00; --radius: 16px; }`,
    },
})

//go:embed updater-window.html
var updaterHTML string

app.Updater.Init(updater.Config{
    // …
    Window: &updater.BuiltinWindow{HTML: updaterHTML},
})

myWin := app.Window.NewWithOptions(application.WebviewWindowOptions{
    Title:                "My App Updater",
    Width:                520, Height: 460,
    HTML:                 updaterHTML,
    AllowSimpleEventEmit: true,  // required — see security note
})
app.Updater.Init(updater.Config{
    // …
    Window: updater.BYOWindow(myWin.AsUpdaterWindow()),
})

Para executar a verificação periodicamente, em vez de usar o clique no menu (ou além dele):

app.Updater.Init(updater.Config{
    CurrentVersion: currentVersion,
    Providers:      []updater.Provider{gh},
    PublicKey:      updaterPublicKey,
    CheckInterval:  6 * time.Hour,
})

Cada intervalo executa o mesmo fluxo CheckAndInstall de um clique manual. Defina Window: updater.WindowNone se quiser que a verificação periódica permaneça silenciosa até que algo seja realmente encontrado — depois, assine EventUpdateAvailable por conta própria para decidir qual experiência apresentar ao usuário.