根本原因是Go模块代理未配置或不可用，导致go get无法拉取golang.org/x/...等被墙路径依赖；需先执行go env -w GO111MODULE=on，再设go env -w GOPROXY=https://goproxy.cn,direct，并确保在正确目录下运行go mod init后安装带版本后缀的iris。
直接原因是 Go 模块代理未配置或不可用，导致 go get 无法拉取 golang.org/x/... 等被墙路径的依赖。这不是 Iris 本身的问题，而是国内网络环境下 Go 默认代理策略失效的共性现象。
报错典型特征：golang.org/x/... 路径 fetch 失败
错误信息里只要出现类似：
package golang.org/x/net/publicsuffix: unrecognized import path "golang.org/x/net/publicsuffix": https fetch: Get "https://golang.org/x/net/publicsuffix?go-get=1": dial tcp 172.217.163.49:443: connectex: A connection attempt failed...
就基本可以锁定是代理问题。Iris 本身不直接依赖 golang.org/x/...，但其间接依赖（如 net/http 相关扩展、go-bindata 等）会触发这些路径的解析。
- 别尝试手动
git clone到$GOPATH/src—— Go Modules 模式下该路径已废弃，不会被识别 - 别用
go get -insecure—— 它只禁用 HTTPS 验证，不解决域名不可达问题 - 确认你不是在 GOPATH mode 下运行（
go env GO111MODULE返回off），否则模块代理设置无效
必须设置 GOPROXY 才能成功安装
执行以下两条命令（顺序不能反）：
go env -w GO111MODULE=on<br>go env -w GOPROXY=https://goproxy.cn,direct
其中 https://goproxy.cn 是七牛提供的稳定国内镜像，direct 表示对私有仓库回退直连（如公司内网 Git）。
- 设置后可运行
go env | findstr GOPROXY（Windows）或go env | grep GOPROXY（macOS/Linux）验证是否生效 - 如果公司有内部代理（如 Nexus Go Proxy），应替换为对应地址，而非盲目套用
goproxy.cn - 某些 IDE（如 Goland）会缓存 GOPROXY 设置，改完后需重启 IDE 或重载项目
安装命令要带版本后缀，避免拉取不兼容分支
Iris v12 主线已弃用无版本后缀的导入路径，直接 go get github.com/kataras/iris 会拉取 master 分支（可能含破坏性变更），且与当前主流文档不匹配。
- 推荐命令：
go get github.com/kataras/iris/v12@v12.2.5（以实际稳定版为准） - 若想用最新 alpha/beta 版，必须显式指定，如：
go get github.com/kataras/iris/v12@v12.2.0-beta3 - 不要混用
v12和v13的依赖——例如iris-contrib/swagger/v12和iris/v13一起用，必然 panic - 执行后检查
go.mod文件中是否写入了github.com/kataras/iris/v12 v12.2.5，而不是github.com/kataras/iris v12.2.5（少/v12就是错的）
module 初始化必须在安装前完成
很多人在空目录下直接 go get，结果提示 go: go.mod file not found in current directory 或依赖写入了全局 pkg 目录，后续构建失败。
- 正确流程是：
mkdir myapp && cd myapp && go mod init myapp && go get github.com/kataras/iris/v12@v12.2.5 -
go mod init必须在项目根目录执行，模块名建议用小写字母+短横线（如myapp），避免用大写或点号（MyApp、my.app）引发后续导入路径问题 - 如果已有
go.mod但内容混乱，可删掉重来；go mod tidy不能修复代理缺失导致的初始拉取失败
最常被忽略的一点：GO111MODULE=on 和 GOPROXY 是环境变量，它们影响的是当前 shell 会话。如果你在 PowerShell 里设置了，又切到 CMD 或 VS Code 的集成终端里执行 go get，那些设置根本没生效——得分别在每个终端里重新设置，或者写进系统级环境变量。
