go mod init 未执行或模块名不合法会导致“go: cannot find main module”等错误，模块名须全小写、无空格下划线；Iris v12需用go mod init myapp、go get github.com/kataras/iris/v12@latest、import路径带/v12，并配置GOPROXY解决国内网络问题。
go mod init 没执行或模块名不合法
终端报错 go: cannot find main module 或 unknown revision，基本是模块初始化没做，或者模块名含大写、空格、下划线。Iris 依赖 Go 模块系统，go mod init 必须在项目根目录执行，且模块名只能是小写字母+数字+短横线（如 myapp，不能是 MyApp 或 my_app）。
实操建议：
- 先删掉当前目录下的
go.mod和go.sum - 运行
go mod init myapp（名字全小写、无符号） - 立刻执行
go get github.com/kataras/iris/v12@latest，注意必须带/v12，漏掉会拉 v11 导致类型不兼容 - 检查生成的
go.mod是否含github.com/kataras/iris/v12 v12.2.11这类行，没有就重试
国内网络导致依赖拉取失败
常见现象是 go get 卡住、超时，或报 proxy.golang.org: no such host。Iris 的 v12 依赖大量 Go 官方生态包，国内直连不稳定。
实操建议：
- 设代理：运行
go env -w GOPROXY=https://mirrors.aliyun.com/goproxy,https://proxy.golang.org - 验证是否生效：
go env GOPROXY应输出上述地址 - 若仍失败，临时加
-insecure（仅调试用）：go get -insecure github.com/kataras/iris/v12 - 别用
go install装 Iris——它不走模块系统，后续import会找不到包
import 路径写错或版本冲突
编译报错 cannot find package "github.com/kataras/iris" 或 undefined: iris.New，大概率是 import 路径没带 /v12，或旧项目残留 v11 引用。
实操建议：
- 所有
import必须写成import "github.com/kataras/iris/v12"，不是.../iris或.../iris/v11 - 检查
go.mod里是否混有github.com/kataras/iris v11.x.x，有就手动删掉整行，再go mod tidy - IDE（如 VS Code）可能缓存旧导入，重启 Go language server 或清
~/.cache/go-build - 运行
go list -m all | grep iris，确认只出现v12版本
校验通过但运行时报类型错误
能 go build 成功，但一运行就 panic：cannot use app (type *iris.Application) as type iris.Application，这是典型的 v11/v12 混用——比如某个间接依赖（如中间件包）还在用 v11 的接口定义。
实操建议：
- 执行
go mod graph | grep iris，看是否有非v12的 iris 子模块被引入 - 用
go mod edit -replace强制统一版本：go mod edit -replace github.com/kataras/iris=github.com/kataras/iris/v12@v12.2.11 - 避免使用未适配 v12 的第三方 Iris 插件（如老版
iris-contrib/middleware），优先用官方内置中间件（iris.Compression、iris.Logger等） - 最稳妥方式：删掉
go.mod，从头go mod init+go get v12，不要复用旧模块配置
go.mod 里明确写着 v12、import 路径带 /v12、go list 输出干净，就不用怀疑 Iris 本身——问题一定出在这三层缝隙里。 
