必须先执行 go mod init 初始化模块,再用 go get github.com/kataras/iris/v12@latest 显式拉取 v12 版本,否则默认安装不兼容的 v11;import 路径必须严格匹配为 "github.com/kataras/iris/v12"。

必须先初始化模块,再显式拉取 v12 版本,否则默认装的是不兼容的 v11 —— 这是 90% 新手启动失败的根源。
go mod init 是硬性前提,跳过就等于没开始
Go 1.11+ 默认启用 module 模式,但新项目不会自动生成 go.mod。不执行 go mod init myapp(myapp 替换为你自己的模块名),后续所有依赖管理都会错乱:
-
go get github.com/kataras/iris/v12表面成功,实际可能 fallback 到 v11,go.mod里带+incompatible -
import "github.com/kataras/iris"编译报错:找不到包 —— 正确路径只能是import "github.com/kataras/iris/v12" -
iris.Context类型不存在、app.Use和app.Get行为异常,全是 v11/v12 路由模型差异导致
go get 命令必须带 /v12@latest,不能省略任何部分
v12 的模块路径和语义化版本规则严格绑定,go get 不写 /v12 就会按旧版解析逻辑降级:
- 错误写法:
go get github.com/kataras/iris→ 拉 v11 - 错误写法:
go get github.com/kataras/iris@latest→ 仍拉 v11(因主分支已切 v12,但 Go 不识别) - 正确命令:
go get github.com/kataras/iris/v12@latest - 若超时卡住,先设代理:
go env -w GOPROXY=https://goproxy.cn,direct - 成功后检查
go.mod:应有类似github.com/kataras/iris/v12 v12.2.4的行,且无+incompatible
代码里 import 路径错一个字符就编译失败
v12 强制要求 import 路径与模块路径完全一致,IDE 自动补全常误导人:
- ❌
import "github.com/kataras/iris"→ 找不到包 - ❌
import "github.com/kataras/iris/v12.2"→ 无效路径 - ✅
import "github.com/kataras/iris/v12"→ 唯一合法路径 - 若 IDE 报红,重启或运行
go mod tidy;仍失败,说明go.sum或vendor里残留了 v11 缓存,需手动清理
跑起来前务必验证基础结构是否完整
最小可运行示例不是测试功能,而是验证安装链路是否真正打通:
package main
import "github.com/kataras/iris/v12"
func main() {
app := iris.New()
app.Get("/", func(ctx iris.Context) {
ctx.Text("Hello Iris!")
})
app.Run(iris.Addr(":8080"))
}
运行后访问 http://localhost:8080 应立刻返回文本。如果 panic、404 或编译失败,问题一定出在前面三步中的某一个 —— 尤其注意 go.mod 内容、import 路径、以及是否残留了旧版缓存。这些细节不显眼,但改错一个就能让整个框架“活”过来。











