//go:embed works by having the Go compiler read specified files at compile time and embed their contents into the binary’s .rodata section. 1) The compiler processes //go:embed directives and reads the listed files relative to the source file. 2) It assigns the content to a variable of type string, []byte, or embed.FS, converting byte slices to strings if needed. 3) For embed.FS, the compiler builds an in-memory file tree storing paths, contents, modes, and modification times. 4) This data is stored in the binary’s read-only section, enabling use via fs.FS methods without runtime dependencies. 5) The directive respects build tags and only includes local files within the module, ensuring self-contained, portable binaries. The embed package provides only the FS type, while the actual embedding is handled by the compiler and linker, making it compile-time asset inclusion akin to constants for files.

The //go:embed directive in Go works by allowing the Go compiler to include static files—like text, JSON, HTML, or binary assets—directly into the compiled binary at build time. But how does it actually work under the hood? Let’s break it down.

It’s a Compiler Feature, Not Runtime Magic

First and most importantly: embed is implemented primarily in the Go compiler and linker, not in the embed package itself. The embed package ("embed") only provides one type: fs.FS, which is an interface for file systems. The real magic happens via the special comment //go:embed.

When the Go compiler sees a //go:embed directive followed by a variable declaration, it:

1. Parses the directive during compilation.
2. Reads the specified files from the filesystem (relative to the Go source file).
3. Stuffs the file contents into a special readonly data section of the binary.
4. Assigns that data to the associated variable (usually of type string, []byte, or embed.FS).

This all happens at compile time, so no external files are needed at runtime.

How the Data Gets Embedded

Here’s a typical example:

package main

import "embed"

//go:embed hello.txt
var content string

func main() {
    println(content)
}

Behind the scenes:

• The compiler sees //go:embed hello.txt and knows it needs to include hello.txt.
• It reads the file and stores its contents as a readonly byte slice in the binary.
• If the target variable is string, the compiler generates code to convert the byte slice to a string at program startup.
• For embed.FS, the compiler builds an in-memory representation of the directory structure, mapping file paths to their embedded content.

This embedded data lives in the .rodata (read-only data) section of the binary, just like constant strings and other literals.

What Happens with embed.FS?

When you embed multiple files into an embed.FS:

//go:embed *.txt
var files embed.FS

The compiler constructs a compile-time file tree. It records:

• File paths
• File contents
• File modes (based on source file permissions)
• Modification times (based on source file, if available)

This tree becomes an immutable embed.FS value that implements fs.FS, fs.ReadDirFS, and fs.ReadFileFS. You can use files.Open(), fs.ReadFile(), etc., just like with a real filesystem.

Internally, Go uses a compact structure to represent this tree—essentially a map of paths to file data, baked into the binary.

Build Constraints and Embedding

The //go:embed directive respects build tags and file system layout. Only files that would be included in the build (based on GOOS, GOARCH, etc.) are considered. Also, you can't embed .go files from the same package unless they’re excluded via build tags.

And importantly: the files must be local—you can’t embed files outside the module or from arbitrary paths.

Summary of Key Points

• //go:embed is processed by the compiler, not the runtime.
• Files are read at compile time and stored in the binary’s .rodata.
• Supported types: string, []byte, embed.FS.
• For embed.FS, Go builds an in-memory file tree with path-to-content mapping.
• No external dependencies at runtime—the binary is self-contained.

So while it feels like magic, it’s really just smart compile-time asset baking. The result? Fast, portable binaries with zero reliance on external files.

Basically, it's like const for whole files.

The above is the detailed content of How does go embed work under the hood?. For more information, please follow other related articles on the PHP Chinese website!