//go:embed para Arquivos e Templates

//go:embed informa ao compilador para copiar arquivos para o seu pacote para que eles sejam enviados dentro do binário.

Você os lê através de string, []byte ou embed.FS sem abrir caminhos no host de implantação.

Resumo

go:embed foi introduzido no Go 1.16 e substituiu a maioria dos geradores de código estilo bindata para ativos estáticos.

A diretiva se aplica a variáveis no mesmo pacote, usando padrões glob relativos ao arquivo de origem.

embed.FS implementa io/fs.FS, então http.FileServer, fs.WalkDir e template.ParseFS se compõem naturalmente.

Dados incorporados são somente leitura; mutate cópias na memória se você precisar alterar o conteúdo em tempo de execução.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

package assets
 
import "embed"
 
//go:embed migrations/*.sql
var Migrations embed.FS
 
//go:embed config/default.yaml
var DefaultConfig []byte

Quando usar isso:

• Envio de migrações SQL ou YAML/JSON padrão com uma CLI ou serviço.
• Empacotamento de templates HTML e UI estática para implantação de binário único.
• Garantir que os ativos existam em testes sem malabarismos de caminhos de fixture.
• Construção de ferramentas que devem rodar offline sem um diretório de configuração.

Exemplo de Trabalho

example.com/app/
  main.go
  assets/
    migrations/
      001_init.sql
    templates/
      home.html

// main.go
package main
 
import (
    "embed"
    "html/template"
    "io/fs"
    "log"
    "net/http"
)
 
//go:embed assets/migrations/*.sql
var migrations embed.FS
 
//go:embed assets/templates/*.html
var templates embed.FS
 
func main() {
    sql, err := fs.ReadFile(migrations, "assets/migrations/001_init.sql")
    if err != nil {
        log.Fatal(err)
    }
    log.Printf("bytes da migração: %d", len(sql))
 
    tpl, err := template.ParseFS(templates, "assets/templates/*.html")
    if err != nil {
        log.Fatal(err)
    }
 
    http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
        _ = tpl.ExecuteTemplate(w, "home.html", nil)
    })
    log.Fatal(http.ListenAndServe(":8080", nil))
}

O que isso demonstra:

• Múltiplas variáveis //go:embed podem existir em um pacote.
• Os caminhos do FS retêm o prefixo do diretório do padrão (assets/migrations/...).
• template.ParseFS carrega templates sem caminhos de disco em tempo de execução.

Mergulho Profundo

Como Funciona

1. O compilador escaneia os comentários //go:embed acima das variáveis de nível de pacote.
2. Arquivos correspondentes são lidos da árvore de origem do módulo durante a compilação.
3. Bytes são armazenados nos metadados do pacote compilado e vinculados ao binário final.
4. Em tempo de execução, embed.FS serve esses bytes através das APIs io/fs.
5. Nenhum hook init lê o sistema de arquivos na máquina de destino.

Regras de Padrão

Servindo Arquivos Estáticos

//go:embed static/*
var static embed.FS
 
sub, _ := fs.Sub(static, "static")
http.Handle("/static/", http.StripPrefix("/static/", http.FileServer(http.FS(sub))))

fs.Sub remove o prefixo incorporado para que os URLs mapeiem de forma limpa.

Notas do Go

import _ "embed" // necessário ao usar //go:embed sem referenciar embed no código

Se você incorporar apenas em []byte e nunca nomear embed.FS, a importação em branco satisfaz o compilador.

Armadilhas

• Caminho FS errado - ReadFile usa o caminho incorporado completo, incluindo diretórios do padrão. Correção: registre fs.WalkDir uma vez ou corresponda exatamente ao prefixo do padrão.
• Esperando recarga ativa - o conteúdo incorporado é fixo no momento da compilação. Correção: use tags de compilação para alternar entre embed e disco em desenvolvimento.
• Binários grandes - incorporar ativos de vários megabytes incha cada implantação. Correção: hospede mídia grande externamente; incorpore apenas o que deve ser local.
• Segredos em embed - arquivos na máquina de compilação são incorporados. Correção: nunca incorpore segredos de produção; injete em tempo de execução.
• Testes e diretório de trabalho - embed ignora os.Chdir em testes porque os dados não são lidos do disco em tempo de execução. Correção: teste através das APIs do FS incorporado.
• Incompatibilidade de nomes de template - ExecuteTemplate usa o nome definido do template, nem sempre o nome do arquivo. Correção: chame tpl.DefinedTemplates() durante o desenvolvimento.

Alternativas

FAQs

Relacionado

• Além da Especificação: Embed, Modos de Compilação e Assembly - visão geral conceitual
• Noções Básicas de Recursos Avançados de Linguagem - exemplos introdutórios de embed
• Restrições de Compilação e Arquivos Específicos da Plataforma - conjuntos de embed por plataforma
• Noções Básicas de Pacotes e Módulos - layout do módulo para ativos

Versões da Pilha: Esta página foi escrita para Go 1.26.x (padrão Green Tea GC, go fix modernizers - verifique o patch na compilação), chi (última - verifique na compilação), gin (última - verifique na compilação), echo (última - verifique na compilação), google.golang.org/grpc (última - verifique na compilação), sigs.k8s.io/controller-runtime (última - verifique na compilação), kubebuilder (última - verifique na compilação), tinygo (última - verifique os alvos da placa na compilação), wazero (última - verifique na compilação) e golangci-lint (última - verifique o conjunto de linters na compilação).