必须先执行go mod init初始化模块，再用go get github.com/kataras/iris/v12@v12.2.5显式安装v12.2.5版；import路径必须为github.com/kataras/iris/v12，否则因版本降级或路径错误导致编译失败、路由不兼容。
go get 安装 Iris 最新版不是直接敲命令就能成的事，尤其在 2026 年当前主流是 v12.2.5（截至你知识库中最新明确版本），而 go get github.com/kataras/iris 默认会拉取旧版（v11 或更早），不加版本约束大概率装错、跑不起来、静态资源挂掉、甚至编译都报错。
GO111MODULE 必须开启，且 GOPROXY 要配对
Go 1.16+ 默认启用模块，但很多老项目或 CI 环境仍可能关闭。不开启会导致 go get 忽略 /v12 后缀，降级到 v11 —— 而 v11 的 app.StaticWeb() 在 v12+ 已废弃，路径逻辑完全不同。
- 运行
go env -w GO111MODULE=on（永久生效） - 国内必须设代理：
go env -w GOPROXY=https://goproxy.cn,direct或https://mirrors.aliyun.com/goproxy - 别信临时
set或export：Windows 命令行关了就丢，Linux shell 重开也失效
安装命令必须带 @v12.2.5 或 @latest
直接 go get github.com/kataras/iris 是陷阱——它不会自动选 v12，而是按 GOPATH 模式找 master 分支，大概率拉到不兼容的旧版。
- 推荐写死版本：
go get github.com/kataras/iris/v12@v12.2.5 - 若想用最新稳定版：
go get github.com/kataras/iris/v12@latest（注意不是github.com/kataras/iris@latest） - 如果提示
unknown revision，说明 GOPROXY 没生效，检查go env GOPROXY输出是否非空 - 安装后，
go.mod中应出现类似：github.com/kataras/iris/v12 v12.2.5，而非github.com/kataras/iris v11.x
导入路径写错 = 编译失败
代码里 import 语句和安装路径必须严格一致，v12 起强制要求带 /v12 后缀，漏掉就报 undefined: iris.New 或 cannot find package。
- ✅ 正确：
import "github.com/kataras/iris/v12" - ❌ 错误：
import "github.com/kataras/iris"（v11 路径，类型不兼容） - ❌ 错误：
import "github.com/kataras/iris/v12.2.5"（版本号不能进 import 路径） - IDE 自动补全有时会推错路径，务必手动核对
初始化项目时别跳过 go mod init
哪怕只是写个 main.go 测试，也得先 go mod init myapp。否则 go run main.go 会绕过模块系统，导致 iris/v12 的依赖解析失败，静默降级或 panic。
- 新建目录后第一件事：
go mod init example.com/myapp - 再
go get github.com/kataras/iris/v12@v12.2.5 -
go run main.go才能正确加载 v12 的iris.Dir、app.HandleDir等新 API - 没
go.mod文件时，go build可能成功，但运行时报panic: interface conversion: interface {} is nil（常见于 Context 初始化失败）
关键点其实就一个：v12 不是“升级”，是“重装”——路径、导入、静态资源 API 全部换血。任何沿用 v11 习惯的地方，都会在启动那一秒给你颜色看。
