静态文件服务

Gin 提供便捷的静态文件服务方法，适用于前端资源、图片、文档等场景。

Static 方法

将目录映射到 URL 路径：

func main() {
    r := gin.Default()

    // 访问 /assets/* 对应 ./static 目录
    r.Static("/assets", "./static")

    r.Run(":8080")
}

目录结构示例：

static/
├── css/
│   └── style.css
├── js/
│   └── app.js
└── images/
    └── logo.png

访问方式：

http://localhost:8080/assets/css/style.css
http://localhost:8080/assets/js/app.js
http://localhost:8080/assets/images/logo.png

StaticFile 方法

映射单个文件：

func main() {
    r := gin.Default()

    // 访问 /favicon.ico 返回 ./favicon.ico
    r.StaticFile("/favicon.ico", "./favicon.ico")

    // 访问 /robots.txt 返回 ./robots.txt
    r.StaticFile("/robots.txt", "./robots.txt")

    r.Run(":8080")
}

StaticFS 方法

使用自定义文件系统：

func main() {
    r := gin.Default()

    // 使用 http.Dir 创建文件系统
    r.StaticFS("/static", http.Dir("./public"))

    r.Run(":8080")
}

组合使用示例

func main() {
    r := gin.Default()

    // 静态资源目录
    r.Static("/assets", "./static/assets")

    // 单个文件
    r.StaticFile("/favicon.ico", "./static/favicon.ico")

    // 前端页面
    r.NoRoute(func(c *gin.Context) {
        c.File("./static/index.html")
    })

    r.Run(":8080")
}

配置优先级

路由匹配按注册顺序进行：

func main() {
    r := gin.Default()

    // 精确匹配优先
    r.StaticFile("/config.json", "./config.json")

    // 目录匹配
    r.Static("/assets", "./static")

    // 动态路由
    r.GET("/assets/:file", func(c *gin.Context) {
        // 这里的动态路由不会匹配，因为前面已经处理
        c.String(200, "dynamic")
    })

    r.Run(":8080")
}

文件下载控制

r.GET("/download/:filename", func(c *gin.Context) {
    filename := c.Param("filename")
    filepath := "./files/" + filename

    // 检查文件是否存在
    if _, err := os.Stat(filepath); os.IsNotExist(err) {
        c.String(404, "文件不存在")
        return
    }

    // 指定下载文件名
    c.FileAttachment(filepath, filename)
})

生产环境建议使用 Nginx 等 Web 服务器处理静态文件，Gin 处理 API 请求。

要点总结

• r.Static() 映射整个目录到 URL 路径
• r.StaticFile() 映射单个文件
• r.StaticFS() 支持自定义文件系统
• 静态路由按注册顺序匹配
• 生产环境推荐 Nginx 处理静态资源