Go embed 嵌入资源实战——静态文件、模板、配置文件嵌入完整方案

老张2026/4/30大约 6 分钟

Go embed 嵌入资源实战——静态文件、模板、配置文件嵌入完整方案

适读人群：需要把 Go 程序打包成单二进制文件的工程师 | 阅读时长：约14分钟 | 核心价值：用 embed 把静态资源打进二进制，实现真正的"一个文件部署"

部署总是要带着一堆文件夹的烦恼

Go 的一大优势是编译成单二进制文件，理论上 scp 上去就能跑。但实际上很多服务还是需要一堆"伴随文件"：HTML 模板、前端静态资源、SQL 迁移脚本、默认配置文件……

部署的时候要额外管理这些文件，还要确保路径正确、版本匹配。有一次我们发版，二进制更新了，但 templates 目录忘了更新，导致线上页面渲染出错，一直没排查出来，直到有人想起来检查文件。

Go 1.16 引入的 embed 包彻底解决了这个问题。

embed 的基本用法

package main

import (
    _ "embed"
    "fmt"
)

// 嵌入单个文件（字符串形式）
//go:embed configs/default.yaml
var defaultConfig string

// 嵌入单个文件（字节切片形式）
//go:embed static/logo.png
var logo []byte

// 嵌入整个目录（embed.FS 形式）
//go:embed templates
var templatesFS embed.FS

//go:embed static
var staticFS embed.FS

func main() {
    fmt.Println(defaultConfig)
    fmt.Printf("logo size: %d bytes\n", len(logo))
}

三种嵌入方式：

string：文本文件，直接可用
[]byte：二进制文件
embed.FS：目录或多文件，像普通文件系统一样操作

完整应用：嵌入前端文件 + 模板

package main

import (
    "embed"
    "fmt"
    "html/template"
    "io/fs"
    "net/http"
    "os"
    "strings"
    "time"
)

//go:embed web/dist
var webDistFS embed.FS

//go:embed templates/*.html
var templatesFS embed.FS

//go:embed configs/default.yaml
var defaultConfigBytes []byte

// 获取子目录的 FS（去掉前缀路径）
func getSubFS(f embed.FS, dir string) fs.FS {
    sub, err := fs.Sub(f, dir)
    if err != nil {
        panic(err)
    }
    return sub
}

func setupStaticHandler() http.Handler {
    // 把 web/dist 目录作为静态文件根目录
    distFS := getSubFS(webDistFS, "web/dist")
    return http.FileServer(http.FS(distFS))
}

func setupTemplates() *template.Template {
    // 从嵌入的 FS 里解析模板
    tmpl, err := template.New("").ParseFS(templatesFS, "templates/*.html")
    if err != nil {
        panic(fmt.Errorf("解析模板失败: %w", err))
    }
    return tmpl
}

type PageData struct {
    Title    string
    User     string
    Items    []string
    BuildAt  time.Time
}

func main() {
    mux := http.NewServeMux()

    // 静态文件服务
    mux.Handle("/static/", http.StripPrefix("/static/", setupStaticHandler()))

    // 模板渲染
    tmpl := setupTemplates()
    mux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
        data := PageData{
            Title:   "Go embed 示例",
            User:    "老张",
            Items:   []string{"Go", "embed", "is", "awesome"},
            BuildAt: time.Now(),
        }
        if err := tmpl.ExecuteTemplate(w, "index.html", data); err != nil {
            http.Error(w, err.Error(), http.StatusInternalServerError)
        }
    })

    // 暴露默认配置
    mux.HandleFunc("/config/default", func(w http.ResponseWriter, r *http.Request) {
        w.Header().Set("Content-Type", "application/yaml")
        w.Write(defaultConfigBytes)
    })

    fmt.Println("Server starting on :8080")
    http.ListenAndServe(":8080", mux)
}

嵌入数据库迁移脚本

这是 embed 最实用的场景之一：把 SQL 迁移文件打进二进制，程序启动时自动执行迁移。

package migrate

import (
    "database/sql"
    "embed"
    "fmt"
    "io/fs"
    "path/filepath"
    "sort"
    "strings"
)

//go:embed migrations/*.sql
var migrationsFS embed.FS

type Migrator struct {
    db *sql.DB
}

func NewMigrator(db *sql.DB) *Migrator {
    return &Migrator{db: db}
}

func (m *Migrator) Migrate() error {
    // 创建迁移记录表（如果不存在）
    _, err := m.db.Exec(`
        CREATE TABLE IF NOT EXISTS schema_migrations (
            version VARCHAR(255) PRIMARY KEY,
            applied_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
        )
    `)
    if err != nil {
        return fmt.Errorf("创建 schema_migrations 表失败: %w", err)
    }

    // 列出所有迁移文件
    entries, err := fs.ReadDir(migrationsFS, "migrations")
    if err != nil {
        return fmt.Errorf("读取迁移文件失败: %w", err)
    }

    // 按文件名排序（确保执行顺序）
    sort.Slice(entries, func(i, j int) bool {
        return entries[i].Name() < entries[j].Name()
    })

    for _, entry := range entries {
        if !strings.HasSuffix(entry.Name(), ".sql") {
            continue
        }

        version := strings.TrimSuffix(entry.Name(), ".sql")

        // 检查是否已经执行过
        var count int
        err := m.db.QueryRow(
            "SELECT COUNT(*) FROM schema_migrations WHERE version = ?", version,
        ).Scan(&count)
        if err != nil {
            return fmt.Errorf("查询迁移状态失败: %w", err)
        }
        if count > 0 {
            fmt.Printf("迁移 %s 已执行，跳过\n", version)
            continue
        }

        // 读取迁移文件内容
        sqlBytes, err := migrationsFS.ReadFile(filepath.Join("migrations", entry.Name()))
        if err != nil {
            return fmt.Errorf("读取迁移文件 %s 失败: %w", entry.Name(), err)
        }

        // 执行迁移（在事务里）
        tx, err := m.db.Begin()
        if err != nil {
            return err
        }

        if _, err := tx.Exec(string(sqlBytes)); err != nil {
            tx.Rollback()
            return fmt.Errorf("执行迁移 %s 失败: %w", version, err)
        }

        if _, err := tx.Exec(
            "INSERT INTO schema_migrations (version) VALUES (?)", version,
        ); err != nil {
            tx.Rollback()
            return fmt.Errorf("记录迁移 %s 失败: %w", version, err)
        }

        if err := tx.Commit(); err != nil {
            return fmt.Errorf("提交迁移 %s 失败: %w", version, err)
        }

        fmt.Printf("迁移 %s 执行成功\n", version)
    }

    return nil
}

迁移文件目录结构：

migrations/
├── 001_create_users.sql
├── 002_create_orders.sql
├── 003_add_user_avatar.sql
└── 004_create_payments.sql

开发模式 vs 生产模式

开发时我们希望能修改静态文件后直接看到效果，不用重新编译。生产模式才需要嵌入。

package assets

import (
    "embed"
    "io/fs"
    "net/http"
    "os"
)

//go:embed web/dist
var embeddedFS embed.FS

// GetStaticFS 根据环境返回静态文件 FS
// 开发模式：从磁盘读（改文件后立即生效）
// 生产模式：从嵌入的 embed.FS 读
func GetStaticFS() (fs.FS, error) {
    if os.Getenv("GO_ENV") == "development" {
        // 开发模式：直接从磁盘读
        return os.DirFS("web/dist"), nil
    }

    // 生产模式：从嵌入的文件系统读
    return fs.Sub(embeddedFS, "web/dist")
}

// GetStaticHandler 返回静态文件处理器
func GetStaticHandler() (http.Handler, error) {
    staticFS, err := GetStaticFS()
    if err != nil {
        return nil, err
    }
    return http.FileServer(http.FS(staticFS)), nil
}