Go ServeMux 为什么路径模式匹配不到

Go ServeMux 路径模式匹配不到，最常见的原因不是注册失败，而是把模式当成了正则表达式。ServeMux 按“方法、主机、路径段”匹配：/users/{id} 只接收一个路径段，/files/{path...} 才能接收后续斜杠；以斜杠结尾的模式还是子树匹配。先按这三条边界检查，再看方法和 Go 版本，通常就能定位 404 或 405。

先确认程序到底使用哪套 ServeMux 语义

Go 1.22 改变了标准库路由模式。如果程序运行在 Go 1.22 或更新版本，下面的模式会把 42 捕获为 id；在旧语义下，{id} 只是字面量。兼容开关 GODEBUG=httpmuxgo121=1 会恢复旧行为，而且只在程序启动时读取。

因此，先看构建环境和启动参数，再判断“匹配不到”。如果注册阶段直接 panic，还要检查模式是否合法：通配符必须是完整路径段，名称必须是合法的 Go 标识符，... 只能出现在末尾。

按路径段区分三种容易混淆的写法

把请求路径拆成段后，匹配范围就清楚了：

注意：/ 是一个全路径兜底模式，不是只匹配根路径；只想处理根路径可以注册 /{$}。通配符值在 handler 中通过 r.PathValue 读取。

package main

import "net/http"

func registerRoutes(mux *http.ServeMux) {
	// 单段资源：/users/42 可以命中，/users/42/profile 不会命中这里。
	mux.HandleFunc("GET /users/{id}", func(w http.ResponseWriter, r *http.Request) {
		id := r.PathValue("id")
		w.Write([]byte("user=" + id))
	})

	// 末尾的 ... 接收剩余路径，适合文件层级或多段资源名。
	mux.HandleFunc("GET /files/{path...}", func(w http.ResponseWriter, r *http.Request) {
		path := r.PathValue("path")
		w.Write([]byte("file=" + path))
	})

	// {$} 只锁定带尾斜杠的目录根，不会覆盖整个 /admin/ 子树。
	mux.HandleFunc("GET /admin/{$}", func(w http.ResponseWriter, r *http.Request) {
		w.Write([]byte("admin root"))
	})
}

尾斜杠、转义路径和查询参数要分开排查

/api/ 是子树模式，/api 没有尾斜杠时，ServeMux 通常会把它重定向到 /api/；如果必须让两个地址有不同处理逻辑，就显式注册 /api。而 /api/{$} 只匹配带斜杠的目录根。

路由匹配会按路径段解码。/a%2Fb 中的编码斜杠仍属于一个请求段，不能把它当成 /a/b 两段来写模式。重复斜杠以及 .、.. 段还可能触发规范化重定向。?page=2 这样的查询字符串不参与模式匹配，需要在 handler 中读取 r.URL.Query()。

最后检查方法、Host 与实际命中的模式

模式没有方法时接受所有方法；写成 GET /users/{id} 后，GET 也覆盖 HEAD，POST 不会命中。若同一路径存在其他方法的 handler，POST 常见结果是 405，而不是单纯的 404。模式前的 Host 也会限制请求主机，测试时要确认 req.Host。

排查时可以先用 mux.Handler(req) 看 ServeMux 认为的模式。它能返回匹配模式或内部重定向 handler，但不会填充 PathValue；要验证通配符值，必须让请求真正经过 mux.ServeHTTP 并在 handler 中读取。

// probe 只观察路由选择；真正读取 PathValue 要走 ServeHTTP。
req := httptest.NewRequest(http.MethodGet, "http://example.test/users/42", nil)
handler, pattern := mux.Handler(req)
fmt.Printf("pattern=%q handler=%T\n", pattern, handler)

// 用 httptest.ResponseRecorder 经过 ServeHTTP，才能在 handler 内读取 id。
recorder := httptest.NewRecorder()
mux.ServeHTTP(recorder, req)
fmt.Println("status=", recorder.Code)

这段探针需要额外导入 fmt、net/http/httptest；它的价值在于把“没有注册”“匹配到了重定向”“方法不允许”和“handler 内读取空值”拆开看。

常见问题

为什么注册了 /users/{id} 还是收不到 /users/42/profile？

因为无省略号通配符只匹配一个路径段。需要接收剩余层级时，把模式改成末尾的 /users/{path...}，或者为更深的固定资源单独注册模式。

为什么 / 会把所有未知路径也接走？

/ 是全路径兜底模式。如果只想处理根路径，使用 /{$}，并为其他路径返回 404。

为什么 mux.Handler 看到了模式，但 PathValue 是空的？

Handler 只做选择，不填充请求的路径值；让请求进入 ServeHTTP 后，在实际 handler 中读取 r.PathValue("id")。