go mod init 必须在项目根目录执行，否则 go build 会报“cannot find module providing package”；正确做法是先创建并进入项目目录，再运行 go mod init 模块名。
go mod init 必须在项目根目录执行，否则 go build 会找不到模块
很多初学者把 main.go 直接丢进 D:\GoProjects 或桌面就跑 go mod init，结果 go build 报错：「cannot find module providing package」。根本原因是 Go 要求 go.mod 所在路径即为模块根目录，且所有 import 路径必须相对于该目录解析。
- 正确做法：先
mkdir myirisapp && cd myirisapp，再go mod init myirisapp - 如果已有
main.go在别处，不要移动文件，而是用go mod init指定模块名（如go mod init github.com/you/myirisapp），然后确保 import 路径与之匹配 -
go get安装的依赖会写入go.mod和go.sum，但不会自动下载到GOPATH/src—— Go 1.16+ 默认启用GO111MODULE=on，所有依赖走GOPATH/pkg/mod
国内拉取 github.com/kataras/iris/v12 必须配代理，否则超时或 403
直接 go get github.com/kataras/iris/v12 在国内大概率失败，错误通常是 Get "https://api.github.com/...": dial tcp 140.82.112.4:443: i/o timeout 或 403 Forbidden。这不是 Iris 本身的问题，而是 GitHub 域名解析和 CDN 限流导致的。
- 临时生效（推荐测试用）：
export GOPROXY=https://goproxy.cn,direct（Linux/macOS）或set GOPROXY=https://goproxy.cn,direct（Windows） - 永久生效：写入 shell 配置（
~/.bashrc）或 Windows 环境变量，注意末尾加,direct，否则私有仓库无法访问 - 别用
goproxy.io—— 它已停服；也别只设https://goproxy.cn不加,direct，否则本地replace或私有模块会失效
iris.New() 启动前必须注册视图、中间件和路由，否则运行时报 panic
常见错误是 main.go 里只写了 app := iris.New() 就调 app.Listen(":8080")，结果启动失败，日志里出现 panic: template: ...: nil pointer dereference 或 http: Server closed 后立即退出。这是因为 Iris 的某些组件（比如 HTML 视图、JWT 中间件）在初始化阶段未被显式挂载，运行时一访问就崩。
- 视图必须注册：若用 HTML 模板，要写
app.RegisterView(iris.HTML("./views", ".html"))，且确保./views目录存在 - 中间件需主动
Use()：比如app.Use(iris.Recover())，不注册 Recovery 中间件，panic 会直接终止进程 - 路由必须定义：哪怕只有
app.Get("/", func(c iris.Context) { c.Text("OK") })，空路由表会导致Listen内部 panic - 数据库连接等外部依赖，建议封装进
newApp(db *sql.DB)函数传入，避免main()里混杂初始化逻辑
IDEA 中 Iris 项目识别失败？检查 go.mod 和 SDK 路径是否匹配
用 IDEA 新建 Iris 项目时，经常出现「Cannot resolve symbol iris」或「Unresolved reference」，即使 go build 能成功。这通常不是代码问题，而是 IDE 缓存或 Go SDK 配置错位。
- 确认 IDEA 里配置的 Go SDK 是你本地安装的完整 Go 目录（如
D:\Go），不是D:\Go\bin或D:\Go\src - 检查项目结构中是否真有
go.mod文件，且内容含require github.com/kataras/iris/v12—— IDEA 依赖它识别模块 - 删掉
.idea目录和go.work（如有），重启 IDEA 并选「Reload project from go.mod」 - 如果用了
replace指向本地 Iris 修改版，IDEA 可能不识别，此时需手动在Settings → Go → Modules中添加该路径为「Go Module Path」
go.mod 路径语义和 GOPROXY 的 ,direct 后缀——少一个字符，就可能让整个构建流程卡在凌晨三点。 
