Iris官方明确要求使用go mod方式安装v12版本，必须指定/v12后缀、配置GO111MODULE=on及GOPROXY，import路径须与go.mod中require完全一致，否则会导致版本错乱或编译失败。
go get 命令在 2026 年已不再被官方推荐用于安装 Iris，尤其是配合 GO111MODULE=on 或现代 Go 项目结构时，它会绕过模块版本控制、忽略 go.mod 约束，甚至拉取非预期的 commit（比如 master 分支的不稳定快照），导致构建失败或运行时 panic。
Iris 官方文档（截至 2026 年）明确要求使用 go mod 方式管理依赖，且必须指定 v12 主版本 —— 因为 Iris v12 是当前唯一活跃维护的稳定系列，v13 尚未发布，而旧版 v11 及更早已归档停更。
确认 Go 环境和模块模式
执行以下命令检查基础环境是否达标：
-
go version：必须 ≥go1.18（Iris v12.2+ 实际最低要求，1.15 已不被 CI 验证） -
go env GO111MODULE：输出应为on；若为auto或off，需手动启用：go env -w GO111MODULE=on -
go env GOPROXY：国内用户务必设置为可用代理，例如：go env -w GOPROXY=https://goproxy.cn,direct
用 go mod get 安装 Iris v12
在你的项目根目录下（含 go.mod 文件），运行：
go get github.com/kataras/iris/v12@latest
注意三点：
- 必须带
/v12后缀，否则 Go 模块系统无法识别主版本，会报错unknown revision或降级到错误的 v0.x 兼容层 - 不要加
-u（升级标志）——它可能把间接依赖（如golog、pio）升到不兼容版本，引发undefined: iris.Context类型错误 - 如果已有旧版残留（如
github.com/kataras/iris无版本后缀），先删掉go.mod中对应行，再go mod tidy
常见失败现象与直击原因
遇到这些提示，基本不是网络问题，而是模块语义没对齐：
-
require github.com/kataras/iris: version "v12.2.0" invalid: module contains a go.mod file, so major version must be compatible: should be v0 or v1, not v12→ 你漏写了/v12，Go 模块认为你在引用一个“无版本”的 v0 包 -
cannot find package "github.com/kataras/iris/v12" in any of ...→go.mod未初始化，先运行go mod init your-project-name - 编译时报
undefined: iris.New→import语句写成了"github.com/kataras/iris"（缺/v12），正确应为"github.com/kataras/iris/v12"
验证安装是否真正生效
仅靠 go get 成功不代表能用。最简验证方式是写个空服务跑起来：
package main
<p>import "github.com/kataras/iris/v12"</p><p>func main() {
app := iris.New()
app.Get("/", func(ctx iris.Context) { ctx.WriteString("ok") })
app.Listen(":8080")
}运行 go run .，访问 http://localhost:8080 返回 ok 才算闭环。中间任何一步失败，大概率是 import 路径、模块版本或 GOPROXY 配置三者之一没对齐。
最容易被忽略的是：Iris 的 import 路径和 go.mod 里 require 的路径必须完全一致，包括大小写和 /v12 —— 这不是约定，是 Go 模块系统的硬性校验规则。
