Iris v12 要求 Go ≥1.21,因依赖 log/slog;需升级 Go、设 GOPROXY、用 iris.Recover 防 panic、静态文件路径须匹配、模板 layout 必须为 ./views/layouts/layout.html 且调用 ctx.View。

go mod init 后 iris/v12 无法导入?检查 Go 版本是否 ≥1.21
直接报 package log/slog is not in GOROOT,不是依赖没下全,是 Go 太老。Iris v12 显式依赖标准库的 log/slog,而该包直到 Go 1.21 才正式稳定引入。用 go version 确认——若输出是 go1.19.13 或 go1.20.12,必须升级。
升级后执行:go mod init myappgo get github.com/kataras/iris/v12@v12.1.8
此时 go build 不再报 slog 缺失。
- 别在 GOPATH/src 下硬建项目目录,v12 不吃那一套
- Windows 用户若用 PowerShell,设置代理要写成
$env:GOPROXY="https://goproxy.cn",不是set - 国内直连 GitHub 失败时,
go get前务必确认GO111MODULE=on且GOPROXY已生效
iris.New() 启动失败:端口被占或路由注册顺序错乱
常见现象是进程启动后立刻退出,无错误日志,或报 listen tcp :8080: bind: address already in use。Iris v12 默认不自动 recover panic,一旦中间件或 handler 报错(比如 nil 指针解引用),服务就静默终止。
建议初始化时加基础防护:
app := iris.New()
app.Use(iris.Recover)
app.Use(iris.Logger)
app.Get("/", func(ctx iris.Context) {
ctx.HTML("Hello Iris v12")
})
app.Listen(":8080")
-
iris.Recover必须在app.Get之前注册,否则 panic 仍会中断进程 - 若改用
app.ConfigureHost自定义http.Server,记得显式传入Addr,否则默认监听:8080可能冲突 - Windows 下杀端口用
netstat -ano | findstr :8080+taskkill /PID xxx /F,别信任务管理器“结束任务”
静态文件 404:Public 目录路径与 ServeFiles 参数不匹配
Iris v12 的 app.HandleDir 和 app.StaticWeb 对路径处理更严格。比如你把图片放在 ./public/images/logo.png,但注册时写:
app.HandleDir("/static", iris.Dir("./public"))
访问 /static/images/logo.png 才能命中;写成 app.HandleDir("/static", iris.Dir("./public/images")) 就会导致 /static/logo.png 才可访问——少一层目录,就全 404。
-
iris.Dir()的路径是物理路径,不支持通配符或相对上层跳转(如../) - 开发期建议用
app.StaticWeb("/static", "./public"),它自动处理 MIME 类型和缓存头 - 生产部署时,Nginx 前置更稳妥,Iris 自带静态服务适合快速验证,别压测
模板渲染空白:Layout 文件名、路径、Render 参数三处易漏
v12 默认用 html/template,要求 layout 文件必须叫 layout.html(不能是 base.html 或 _layout.html),且必须放在 ./views/layouts/ 下。调用 ctx.View 时若漏传 layout 名,或传错大小写,页面就纯白。
正确结构示例:
./views/ ├── layouts/ │ └── layout.html └── home.html
对应代码:
app.RegisterView(iris.HTML("./views", ".html"))
app.Get("/", func(ctx iris.Context) {
ctx.View("home.html") // 自动套 layout.html
})
-
RegisterView的第二个参数是扩展名,必须带点,写"html"会找不到任何模板 - 如果自定义 layout 名,得用
ctx.ViewLayout("mylayout.html")提前声明,且路径仍需在layouts/子目录下 - 模板里用
{{ yield }}插入内容,不是{{ template "main" . }},后者是原生 html/template 语法,v12 不识别
最常被忽略的是:v12 的 iris.Dir、iris.HTML 路径全按当前工作目录(os.Getwd())解析,不是 go.mod 所在目录。调试时先 fmt.Println(os.Getwd()) 看一眼,比猜强十倍。











