如何使用Golang Gorilla Mux替代原生http包托管Next.js应用

1. 前置准备：导出Next.js静态产物 #

先在Next.js项目目录执行构建命令，生成可直接托管的纯静态文件：

next build && next export

构建完成后默认会生成out目录，将整个目录复制到Go服务项目中，比如放到./static/next_out路径下，最终项目结构参考：

your-go-project/
├── controllers/
│   └── routes.go
├── static/
│   └── next_out/  # 存放Next.js导出的所有静态文件
│       ├── _next/
│       ├── index.html
│       └── 其他页面、公共静态资源
└── main.go

2. routes.go核心实现 #

Gorilla Mux遵循先注册先匹配的规则，必须先注册后端业务API路由，最后注册静态资源规则和前端路由兜底，否则API请求会被静态文件处理器提前拦截。
具体代码示例：

package controllers

import (
	"net/http"
	"os"
	"path/filepath"

	"github.com/gorilla/mux"
)

// RegisterRoutes 注册全量路由
func RegisterRoutes() *mux.Router {
	r := mux.NewRouter()

	// 先注册所有后端业务API路由，示例：
	// r.HandleFunc("/api/user/info", GetUserInfo).Methods("GET")
	// r.HandleFunc("/api/order/create", CreateOrder).Methods("POST")

	// 托管Next.js核心静态资源目录（打包后的JS、CSS、字体、图片等）
	nextStaticFS := http.Dir(filepath.Join("static", "next_out", "_next"))
	r.PathPrefix("/_next/").Handler(http.StripPrefix("/_next/", http.FileServer(nextStaticFS)))

	// 托管根路径访问，直接返回入口HTML
	r.HandleFunc("/", func(w http.ResponseWriter, req *http.Request) {
		indexPath := filepath.Join("static", "next_out", "index.html")
		w.Header().Set("Content-Type", "text/html; charset=utf-8")
		http.ServeFile(w, req, indexPath)
	}).Methods("GET")

	// 配置未匹配路由的兜底逻辑，适配Next.js客户端路由
	r.NotFoundHandler = http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) {
		// 非GET请求的未匹配路径正常返回404
		if req.Method != http.MethodGet {
			http.NotFound(w, req)
			return
		}

		// 先判断请求路径是否对应真实存在的静态文件
		targetFile := filepath.Join("static", "next_out", req.URL.Path)
		_, err := os.Stat(targetFile)
		if err == nil {
			http.ServeFile(w, req, targetFile)
			return
		}

		// 静态文件不存在时返回入口HTML，交给Next.js前端路由匹配渲染
		w.Header().Set("Content-Type", "text/html; charset=utf-8")
		http.ServeFile(w, req, filepath.Join("static", "next_out", "index.html"))
	})

	return r
}

3. 避坑说明 #

• 生产环境不要硬编码静态文件相对路径，建议做成可配置项，同时启动服务时注意工作目录和静态路径的匹配关系，避免出现文件404
• /_next/目录下的资源文件名自带内容hash，可以配置1年以上的强缓存减少重复请求；HTML入口文件不要配置强缓存，避免版本更新不生效
• 如果Next.js构建时配置了basePath，所有静态路由前缀要同步适配，比如basePath设为/admin时，/_next/前缀需要调整为/admin/_next/
• 如果后端API统一带/api前缀，可以给API路由单独划分子路由组，进一步避免和前端路由规则冲突

内容的提问来源于stack exchange，提问作者Manos Kalogeropoulos