Go 1.16+ 默认启用 Go Modules，无需配置 GOPATH；关键是要确保 GO111MODULE=on 且 go mod init 的模块路径与 import 路径严格一致。
确认当前版本和模块状态
先检查项目是否已启用 Go Modules，执行 go env GO111MODULE，输出必须是 on；若为 auto 或 off，需手动开启：go env -w GO111MODULE=on。再确认 go.mod 中是否已有 github.com/kataras/iris/v12 条目——没有就说明压根没引入过，有则看其版本号（如 v12.2.0-beta6.0.20221125222511-29c29e79e5da），越旧越可能缺失安全修复或新 API。
用 go get 拉取 v12 最新版（非 master）
别用 @master，它不稳定且可能破坏兼容性；官方推荐稳定发布分支。执行：
go get github.com/kataras/iris/v12@latest
这会自动解析最新 tagged release（如 v12.2.5）。如果报错提示找不到版本，常见原因是 GOPROXY 配置失效或网络异常，此时应重设代理：
go env -w GOPROXY=https://goproxy.cn,direct- 再运行
go mod tidy清理未引用依赖并补全go.sum
注意：go get -u 在较新 Go 版本中已被弱化，-u 不再递归更新间接依赖，所以只对 iris/v12 显式指定即可。
验证安装是否生效
编译时若出现类似 cannot use string as iris.Handler 的错误，大概率是代码里还混着旧写法（比如把字符串直接传给 app.HandleDir），不是框架没装好。真正装成功的标志是：
-
go build通过，无 import 错误 - 启动后访问
/debug/pprof/能看到 Iris 自带的性能分析端点（v12.2+ 默认启用） - 日志中出现类似
[INFO] Iris version: v12.2.5的输出（需开启 logger）
如果仍用 app.StaticWeb()，它不会报编译错，但运行时静态资源 404 —— 这属于迁移遗漏，不是安装问题。
升级后必须检查的兼容性断点
v12 系列不是完全向后兼容的，尤其从 beta 升到正式版时容易踩坑：
-
iris.Context方法签名微调：比如ctx.ReadForm在 v12.2.0+ 要求结构体字段带 tag，旧代码若靠默认行为可能漏绑定 -
app.UseRouter已移除，改用app.Use+iris.Compression等显式中间件 - 模板引擎注册方式变更：v12.2+ 推荐用
iris.HTML替代iris.Jade等独立包，后者虽可用但不再维护 - 所有
iris.Dir()调用必须传绝对路径，相对路径在 systemd 或容器中必挂，这点和安装无关，但升级后常因部署环境变化暴露出来
最隐蔽的问题是：升级后没改代码，服务能跑，但某些路由参数解析（比如 {id:int min(1)}）行为更严格了，原来容忍的非法输入现在直接 400 —— 这不是 bug，是防护增强，但线上接口可能突然变脆弱。
