必须在go get前执行go mod init：先在项目根目录运行go mod init myapp，确认go.mod首行为module myapp，再执行go get github.com/kataras/iris/v12@latest，且代码中import路径必须为github.com/kataras/iris/v12。
go mod init 必须在 go get 之前执行
不初始化模块就直接 go get github.com/kataras/iris/v12，Go 会 fallback 到 v11（带 +incompatible 标记），后续所有路由、中间件、iris.Context 类型都会报错。这不是网络问题，是 Go Module 的语义化版本解析规则决定的。
必须按顺序操作：
- 在项目根目录下运行
go mod init myapp（myapp替换为你的模块名） - 检查生成的
go.mod文件首行是否为module myapp，不是就手动改 - 确认当前路径是模块根目录：
go list -m应输出你的模块名 - 再执行
go get github.com/kataras/iris/v12@latest
import 路径必须含 /v12，且不能省略
代码里写 import "github.com/kataras/iris" 会编译失败——v12 的正式 import path 就是 github.com/kataras/iris/v12，少一个 /v12，Go 就加载不到正确版本。
常见连带问题：
- IDE（如 GoLand）提示报红？重启 IDE 或运行
go mod tidy - 仍提示找不到
iris.Context？说明实际加载的是 v11，回退检查前一步的go.mod内容 - 旧项目残留
vendor/目录或过期go.sum？删掉重试，否则go build表面成功，运行时 panic
验证 iris.Run 是否真正启动成功
只看到 Starting server on :8080 不代表稳定可用。v12 启动后必须能响应 HTTP 请求且无 panic 日志，才算通过基础兼容性检查。
最小验证代码：
package main
import "github.com/kataras/iris/v12"
func main() {
app := iris.New()
app.Get("/ping", func(ctx iris.Context) {
ctx.WriteString("pong")
})
app.Run(iris.Addr(":8080"))
}
然后执行：
- 终端运行
curl http://localhost:8080/ping，应返回pong - 观察控制台日志：不能出现
panic: interface conversion或nil pointer - 若用
app.Use(...)注册中间件后崩溃，说明中间件注册方式写法错误（v12 是app.Use(mw)，不是 v11 的app.UseFunc(...)）
swag 文档集成要匹配 v12 分支
用 swag init 生成文档后访问 /swagger/index.html 白屏或 404，大概率是 swagger 版本没对齐。
关键约束：
- Iris v12 必须配
github.com/iris-contrib/swagger/v12，不能用无后缀或/v13 -
swagCLI 工具必须是v1.10.5，更高版生成的docs/docs.go会引用v2路径，与 v12 不兼容 - 注解必须写在 handler 函数上方，且
@Summary和@Description缺一不可 - 每次改注释后必须重跑
swag init -g main.go，否则前端看不到更新
最常被忽略的是：没删干净旧缓存的 go.sum 或残留的 vendor，导致 go run main.go 看似启动成功，但 /swagger/doc.json 返回 404 —— 这时候查 go.mod 里的 iris-contrib/swagger 行，看是不是带了 +incompatible。
