beego自定义模板函数必须在beego.run()前注册，且函数需单入参单出参、首字母大写、非指针接收者、非闭包；模板中仅支持管道语法调用，如{{.time|formattimestr}}。
必须在 beego.Run() 调用前注册，否则模板里调用会静默失败或 panic。
函数定义必须满足签名规范
Beego 只接受单入参、单出参（或带 error）的函数，且参数和返回值类型需明确。不支持多返回值（如 (string, error) 会被忽略 error）、不支持指针接收者、不支持闭包。
- ✅ 正确写法：
func FormatTimeStr(timestr string) string或func SubAndReplace(s string, n int) string - ❌ 错误写法：
func getUser(id int) (*User, error)—— Beego 会丢弃第二个返回值，可能导致空指针或意外字符串输出 - ⚠️ 注意：函数体里不能直接 panic，否则整个模板渲染中断；建议用空字符串或默认值兜底
注册时机和位置很关键
注册动作必须发生在 beego.Run() 之前，且通常放在 init() 函数中。如果放在 controller 或 handler 里，根本不会生效。
- 推荐路径：新建
utils/functions.go，在其中定义函数并导出Init()，然后在main.go的init()里调用它 - 别在
main()函数里注册 ——beego.Run()内部会提前初始化模板引擎，此时再调用beego.AddFuncMap()已晚 - 注册名（第一个参数）必须是合法标识符，比如
"formatTime"可以，"format-time"或"Format Time"会导致模板解析报错function "format-time" not defined
模板中调用时注意上下文和管道语法
自定义函数只能通过 pipeline（|）传入单个值，不能像普通函数那样传多个参数。如果需要多参，得提前组合成 struct 或 map 传入。
- ✅ 正确：
{{ .CreatedAt | FormatTimeStr }}或{{ "2026-09-21 01:00:00" | SubAndReplace 10 }}（注意：Go 模板支持尾部字面量参数，但 Beego 版本需 ≥1.12.3） - ❌ 错误：
{{ FormatTimeStr .CreatedAt }}—— 这是函数调用语法，Beego 模板不支持 - ⚠️ 常见坑：如果传入的是
nil或空字符串，函数内部要主动判断，否则str[0:n]会 panic；例如SubAndReplace应先检查len(str) == 0
调试时看不到错误？检查这几个地方
模板函数失效往往没有明显报错，容易卡在“怎么就是不执行”。优先排查这三项：
- 是否在
beego.Run()前注册？加一行log.Println("func registered")到Init()里确认执行时机 - 模板文件后缀是不是
.tpl？Beego 默认只处理该后缀，用.html且未配置beego.BConfig.WebConfig.TemplateExt = "html"会导致函数不加载 - 函数是否导出？Go 规则：首字母必须大写，
formatTimeStr不行，必须是FormatTimeStr
最易被忽略的一点：Beego 模板函数不支持运行时热更新。改了函数逻辑必须重启进程，bee run 虽能重编译，但旧注册表不会自动清理，有时需手动删掉 ./_obj 目录再试。
