(6) 静态前端网站容器化 - 【源码解读】 使用 gin FS 模式为什么无限 301 重定向了？

建议点击 查看原文 查看最新内容。

原文链接: https://typonotes.com/posts/2025/02/09/gin-static-fs-301-redirect/

为了解决 BrowserRouter 模式下的， History API Fallback 问题。 我们在后端服务器做了一些兼容配置。

  1. (4) 静态前端容器化 - 单页面应用(SAP) History API Fallback - 刷新 404

但是由于 gin 对于 StaticFS() 和 FileFromFS() 两个方法的实现问题， 造成了无限 301 重定向到首页的问题。

今天我们就来跟着 gin 源码一起看看问题出在哪里。

c.File 本地文件

先来回顾 本地目录的中间件 代码怎么实现的。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

func HistoryAPIFallback() func(c *gin.Context) {
	return func(c *gin.Context) {

		path := c.Request.URL.Path
		// 如果是 API 请求，或者是静态资源（JS、CSS、图片），则放行
		if strings.HasPrefix(path, "/api/") || strings.Contains(path, ".") {
			c.Next()
			return
		}

		// 返回固定内容。
		c.File("dist/index.html")
		c.Abort() // 中断后续流程。
	}
}

这里使用了 gin 封装的 c.File() 方法。

1
2
3
4

// File writes the specified file into the body stream in an efficient way.
func (c *Context) File(filepath string) {
	http.ServeFile(c.Writer, c.Request, filepath)
}

调用了标准库的 http.ServeFile() 方法， 可以看到在实现的时候， 为 serveFile 设置了 redirect=false (2)。

这也是为什么使用 c.File() 方法没有 301 条转的原因。

c.FileFromFS FS 文件: 问题所在

在 gin 中同样为 FS 读取文件提供了一个方法 c.FileFromFS。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

// FileFromFS writes the specified file from http.FileSystem into the body stream in an efficient way.
func (c *Context) FileFromFS(filepath string, fs http.FileSystem) {
	defer func(old string) {
		c.Request.URL.Path = old
	}(c.Request.URL.Path)

	c.Request.URL.Path = filepath

	http.FileServer(fs).ServeHTTP(c.Writer, c.Request)
}

其实现方法并不是与 c.File 中一样， 直接使用 serveFile， 而是使用了 ServeHTTP 接口方法。

1
2
3

type Handler interface {
	ServeHTTP(ResponseWriter, *Request)
}

对于接口，我们要看的是 实现对象 http.FileServer(fs)

在图中可以看到， ServeHTTP 同样使用了 serveFile， 但是设置了 redirect=true。

就是因为这个， 才会在使用 FileFromFS 的时候出现 301 跳转。

解决方法

解决方法也很简单， 不使用 gin 为我们封装 c.FileFromFS 方法。 而是直接使用 原生方法 http.ServeFileFS。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

// HistoryAPIFallback 用于前端路由的处理 for History of BrowserRouter
func HistoryAPIFallback(fsys fs.FS) func(c *gin.Context) {
	return func(c *gin.Context) {

		path := c.Request.URL.Path
		// 如果是 API 请求，或者是静态资源（JS、CSS、图片），则放行
		if strings.HasPrefix(path, "/api/") || strings.Contains(path, ".") {
			c.Next()
			return
		}

		// 解决方法： 使用 http.ServeFileFS 替代 ServeHTTP
		http.ServeFileFS(c.Writer, c.Request, fsys, "index.html")
		c.Abort()
	}
}

为什么会无限跳转呢？

造成无限跳转的原因， 是在实现中间件 HistoryAPIFallback 的判断检查上的疏漏。

没有对跳转后的路径 / 进行判断。 因此每次都命中 c.FileFromFS， 进行跳转。

redirect=true 时怎样实现的？ 效果时什么？

条件比较复杂，建议直接看源码。

当访问 http://example.com/ 这样的 目录路径， 默认读取 index.html 作为页面内容。

简单来说 redirect=true 就是针对 index.html 的路径优化， 删除路径中的 index.html， 跳转到 目录路径。

http://example.com/index.html -> https://example.com/
http://example.com/dist/index.html -> https://example.com/dist/