http.FileServer 是 Go 中最轻量的静态文件服务方式，需配合 http.StripPrefix 处理路径前缀，禁用目录列表、添加缓存头和 MIME 类型支持，并注意 embed.FS 的正确使用方式。
用 http.FileServer 快速启动静态文件服务
Go 标准库的 http.FileServer 是最轻量、最直接的方式，适合开发调试或简单部署。它本质是一个 http.Handler，把本地目录映射为 HTTP 路径。
关键点在于路径处理：默认会暴露整个文件系统结构，必须用 http.StripPrefix 去掉 URL 前缀，否则请求 /static/js/app.js 会去查找磁盘上 static/static/js/app.js。
package main
<p>import (
"net/http"
"log"
)</p><p>func main() {
fs := http.FileServer(http.Dir("./public"))
http.Handle("/static/", http.StripPrefix("/static/", fs))</p><pre class='brush:php;toolbar:false;'>log.Println("Server starting on :8080")
log.Fatal(http.ListenAndServe(":8080", nil))}
- 假设静态资源放在项目根目录下的
./public文件夹 -
/static/是浏览器访问的 URL 前缀，StripPrefix保证只把/static/xxx中的xxx传给FileServer - 如果直接用
http.Handle("/", fs)，访问/会尝试读取./public/index.html，但子路径（如/css/style.css）可能因路径拼接出错而 404
处理 404 和目录遍历风险
默认 FileServer 允许列出目录内容（当无 index.html 时），且不校验路径是否越界——攻击者可通过 ../../../etc/passwd 尝试读取敏感文件。
立即学习“go语言免费学习笔记（深入）”；
Go 1.16+ 的 http.Dir 已内置基础防护（拒绝含 .. 的路径），但仍建议显式禁用目录列表，并自定义 404 响应。
package main
<p>import (
"net/http"
"os"
"strings"
)</p><p>type noListDir struct{ http.Dir }</p><p>func (d noListDir) Open(name string) (http.File, error) {
f, err := d.Dir.Open(name)
if err != nil {
return nil, err
}
stat, err := f.Stat()
if err != nil || stat.IsDir() {
// 禁止目录列表；若请求的是目录且无 index.html，返回 404
f.Close()
return nil, os.ErrNotExist
}
return f, nil
}</p><p>func main() {
fs := http.FileServer(noListDir{http.Dir("./public")})
http.Handle("/static/", http.StripPrefix("/static/", fs))
http.ListenAndServe(":8080", nil)
}- 重写
Open方法，在检测到目录且无默认页时主动返回os.ErrNotExist，触发 404 - 不依赖
http.ServeFile单文件模式——它无法处理多级路径和缓存头 - 生产环境务必配合反向代理（如 Nginx）做路径收敛，避免 Go 服务直面公网路径构造攻击
添加缓存头与 MIME 类型支持
浏览器默认对静态资源缓存很弱，FileServer 不自动设置 Cache-Control 或 ETag，需手动包装 handler。
MIME 类型由 http.DetectContentType 或 mime.TypeByExtension 决定，但后者依赖文件扩展名，且 Go 默认未注册所有类型（如 .webp、.avif）。
package main
<p>import (
"net/http"
"time"
"mime"
)</p><p>func cacheHandler(h http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
// 对常见静态资源加 1 小时缓存
if strings.HasSuffix(r.URL.Path, ".js") ||
strings.HasSuffix(r.URL.Path, ".css") ||
strings.HasSuffix(r.URL.Path, ".png") ||
strings.HasSuffix(r.URL.Path, ".jpg") ||
strings.HasSuffix(r.URL.Path, ".webp") {
w.Header().Set("Cache-Control", "public, max-age=3600")
}
h.ServeHTTP(w, r)
})
}</p><p>func main() {
// 注册 webp 支持（Go 1.21+ 已内置，旧版本需手动）
mime.AddExtensionType(".webp", "image/webp")</p><pre class='brush:php;toolbar:false;'>fs := http.FileServer(http.Dir("./public"))
http.Handle("/static/", cacheHandler(http.StripPrefix("/static/", fs)))
http.ListenAndServe(":8080", nil)}
- 缓存策略按后缀判断比正则更轻量，适合多数场景；更精细的控制（如版本哈希文件）应交由构建工具生成带 hash 的文件名
-
mime.AddExtensionType必须在http.FileServer初始化前调用，否则首次请求时类型已缓存 - 不要在 handler 里用
http.ServeContent手动实现 ETag ——FileServer内部已基于文件修改时间生成，足够可靠
为什么不用 embed.FS？适用场景在哪
embed.FS 把静态文件编译进二进制，适合单文件分发、容器镜像精简或防止资源被篡改。但它不支持运行时热更新，且调试期每次改 HTML/CSS 都要重新编译。
典型误用：用 embed.FS + http.FileServer 直接传入，会 panic —— 因为 embed.FS 不满足 http.FileSystem 接口（缺少 Open 方法返回 http.File）。
package main
<p>import (
"embed"
"net/http"
"io/fs"
)</p><p>//go:embed public/*
var staticFiles embed.FS</p><p>func main() {
// 正确做法：用 http.FS 包装 embed.FS，并确保路径 clean
fsys, _ := fs.Sub(staticFiles, "public")
http.Handle("/static/", http.StripPrefix("/static/", http.FileServer(http.FS(fsys))))</p><pre class='brush:php;toolbar:false;'>http.ListenAndServe(":8080", nil)}
-
fs.Sub是关键，它把embed.FS的子路径转为可被http.FileServer消费的fs.FS - 嵌入的路径必须是字面量（
public/*），不能是变量；且public/下不能有符号链接（embed 不支持） - 如果项目同时需要开发期热加载和生产期嵌入，建议用构建 tag 分离两套 server 启动逻辑，而不是 runtime 判断
真正难处理的从来不是启动一行服务，而是路径语义一致性：开发时的 ./public、构建产物的 dist/、Docker COPY 的目标路径、反向代理的 location 匹配——这些地方只要一个斜杠或前缀没对齐，就全是 404。
