beego路由不匹配（notmatch）根本原因是routers包未被导入导致init()未执行；需在main.go中空白导入_ "yourapp/routers"，并确认router.go内已调用beego.router()注册路由。
Beego框架在开发中频繁出现session未启用、模板找不到、连接被劫持、依赖缺失等报错，直接阻断服务启动或请求处理，必须按错误类型精准定位并修正。
Session开启失败：nil pointer dereference
报错信息形如 [config.go:191] Handler crashed with error runtime error: invalid memory address or nil pointer dereference，本质是 session 对象为 nil，常发生在调用 c.StartSession() 或读写 session 前未真正启用。
方法一：通过配置文件启用（推荐）
打开 conf/app.conf，在 [dev] 或 [prod] 区块下添加一行：
【sessionon = true】
注意：这一行末尾不能有任何空格或注释，否则 beego 会静默忽略该配置，导致 session 仍为未启用状态。
方法二：代码中强制启用
在 main.go 的 func main() 开头、beego.Run() 之前插入：beego.BConfig.WebConfig.Session.SessionOn = true
模板文件未找到：can't find template file in the path
此错误多出现在 WebSocket 控制器、API 接口控制器等本就不该渲染 HTML 模板的场景中。Beego 默认会在 Controller 方法执行完后自动调用 Render()，若未指定模板或模板路径不存在，就立即 panic。
第一步：确认是否真需要模板
如果当前控制器只返回 JSON、升级 WebSocket 连接、或直接 WriteString，那模板就是多余的。
第二步：关闭当前控制器的自动渲染
在对应 Controller 的方法开头添加：c.EnableRender = false
这比全局关闭 autorender = false 更安全，避免影响其他正常使用模板的页面。
第三步：检查模板路径命名是否匹配
例如 MainController.Get() 默认查找 views/main/get.html；若实际文件是 views/main/index.html，需显式设置：c.TplName = "main/index.html"
HTTP 响应写入劫持连接：response.WriteHeader on hijacked connection
这个错误专属于 WebSocket 场景——当调用 upgrader.Upgrade() 成功后，底层 TCP 连接已被“劫持”，原始 HTTP ResponseWriter 不再可用。但 Beego 仍在方法结束后试图调用 WriteHeader()，触发 panic。
方法一：禁用自动渲染（最简）
在对应 Controller 的 Get 方法第一行写：c.EnableRender = false
方法二：用 NSRouter 替代默认路由（更可控）
在 routers/router.go 中改用命名空间路由：beego.NSRouter("/websocket", &controllers.WebSocketController{}, "get:Get")
再在 Controller 中确保不调用任何与响应体相关的函数（如 c.Data["json"]、c.ServeJSON()）。
注意：绝不能在 Upgrade 后再调用 c.Ctx.ResponseWriter.Write() 或 c.Ctx.WriteString()，这类操作必然失败。
go.mod 依赖缺失：missing go.sum entry for module
执行 bee run 时提示类似 missing go.sum entry for module github.com/beego/beego/v2/server/web，说明本地 go.mod 已声明依赖，但 go.sum 缺失校验项，常见于项目迁移、git clone 后未完整拉取依赖。
① 进入项目根目录，确认存在 go.mod 文件。
② 执行：go mod tidy —— 它会自动下载缺失模块、补齐 go.sum、清理未引用项。
③ 若提示 go: downloading github.com/... 后卡住，检查 GOPROXY 是否生效：go env GOPROXY，非国内环境建议设为 https://goproxy.cn,direct。
④ 最后运行：bee run
