Go embed部署静态文件至Docker时CSS文件404问题排查

核心原因：Embed FS的路径结构与路由不匹配 #

用http.Dir("./static")时，文件服务器的根目录直接指向static文件夹，因此HTML中/style.css的引用能直接命中static/style.css。但使用embed时，嵌入的文件会保留原目录层级，导致staticFiles中的文件路径为static/style.css，而非根目录下的style.css，这就会造成404。

具体解决步骤 #

1. 使用fs.Sub调整Embed FS的根目录 #

这是最直接的解决方案，将嵌入的static文件夹作为新的文件系统根，让FileServer的行为和http.Dir一致：

package main

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

//go:embed static/*
var staticFiles embed.FS

func main() {
	// 将static目录作为新的FS根
	staticFS, err := fs.Sub(staticFiles, "static")
	if err != nil {
		log.Fatalf("Failed to create sub FS: %v", err)
	}

	// 注册静态文件路由，此时访问/style.css会对应static/style.css
	http.Handle("/", http.FileServer(http.FS(staticFS)))

	// 模板处理逻辑（保持原有正常逻辑即可）
	// ...

	log.Println("Server starting on :8080")
	log.Fatal(http.ListenAndServe(":8080", nil))
}

2. 调整路由前缀与HTML引用路径 #

如果不想修改FS结构，也可以调整路由规则，并确保HTML中的引用路径匹配Embed FS的实际路径：

• 路由注册：

  // 访问/static/style.css时，映射到staticFiles中的static/style.css
  http.Handle("/static/", http.StripPrefix("/static/", http.FileServer(http.FS(staticFiles))))
  

• HTML中修改引用：

  <link rel="stylesheet" href="/static/style.css">
  

3. 检查Embed声明的路径正确性 #

确保//go:embed的路径与项目结构匹配：

• 如果main.go在项目根目录，static文件夹也在根目录，//go:embed static/*是正确的。
• 如果main.go在子目录（如cmd/server/），则需要使用相对路径：//go:embed ../../static/*。

4. 验证Embed内容（调试用） #

可以在代码中打印嵌入的文件列表，确认文件是否正确嵌入：

func listEmbeddedFiles(fs embed.FS) {
	fs.WalkDir(".", func(path string, d fs.DirEntry, err error) error {
		if err != nil {
			return err
		}
		log.Println("Embedded file:", path)
		return nil
	})
}

// 在main中调用
listEmbeddedFiles(staticFiles)

这样就能快速确认style.css的路径是否符合预期。

内容的提问来源于stack exchange，提问作者Edison Spencer