跑通iris项目最常卡在编译阶段：未执行go mod init或handler中误用*context.context而非iris.context，导致undefined: iris或cannot find package错误；v12强制要求模块初始化和iris.context类型，缺一不可。
跑通 Iris 项目最常卡在编译阶段，而不是运行时——iris.Context 类型写错或 go mod init 没执行，直接导致 undefined: iris 或 cannot find package "github.com/kataras/iris/v12"，连 go run 都进不去。
为什么 iris.Context 编译不过？
v12 彻底移除了旧版 *context.Context 用法，所有 handler 必须显式使用 iris.Context。这不是可选适配，是类型强制约束。
- 错误写法：
func(c *context.Context)——context包已不导出，类型也不匹配 - 正确写法：
func(ctx iris.Context)，且必须import "github.com/kataras/iris/v12" - 别手动 import
"github.com/kataras/iris/v12/context"，这个路径在 v12 中不存在 - IDE 自动补全有时会推旧包名，务必核对导入路径是否含
/v12
go mod init 漏掉就等于没开始
没初始化模块，go get 安装的依赖不会写入 go.mod，go run 也找不到包。这不是网络问题，是 Go Modules 体系未激活。
- 必须在项目根目录执行：
go mod init myapp（名称不能含空格或大写） - 接着执行：
go get github.com/kataras/iris/v12@latest，必须带/v12和@latest - 检查
go.mod是否含类似github.com/kataras/iris/v12 v12.2.11的行，没有就重试 - 如果已有
go.mod但没 iris 条目，删掉后重新go mod init更稳妥
app.Listen() 启动失败的常见原因
app.Run() 已被标记为 deprecated，继续用它可能触发警告甚至后续版本报错；而 Listen() 参数顺序和配置项不匹配，会导致监听失败或协议不生效。
- 基础用法：
app.Listen(":8080")，不是app.Run(iris.Addr(":8080")) - 要开调试日志：
app.Listen(":8080", iris.WithLogLevel("debug"))，第二个参数才是配置选项 - HTTPS 不是改端口就行：
app.ListenTLS(":443", "cert.pem", "key.pem")，或用iris.TLS构造配置 - Unix socket：
app.Listen(iris.Unix("/tmp/iris.sock"))，不能传字符串路径
中间件不生效？检查注册顺序
app.Use() 必须在所有 app.Get()、app.Post() 等路由注册之前调用，否则对已注册的路由完全无效——这是静态注册机制决定的，不是 bug。
- 正确顺序：
app := iris.New()→app.Use(...)→app.Get(...)→app.Listen(...) -
iris.Compression默认只压缩 >1KB 的响应体，小响应不压，容易误判“没生效” - 局部启用中间件：
app.Party("/api").Use(...).Get(...)，比全局更可控 - 自定义中间件里别忘了调用
ctx.Next()，否则后续 handler 不会执行
最易被忽略的是 go.mod init 这一步，以及 iris.Context 类型变更；一旦模块没初始化或上下文类型写错，编译器直接拒绝，连运行机会都没有。调试时先看编译错误，再查 go.mod 内容和 handler 函数签名，比盲目加日志更高效。
