XORM报错主因是驱动未注册或连接超时；需检查import中是否含下划线导入MySQL驱动、执行go mod tidy、用sql.Drivers()验证注册状态，并在DSN或context中显式设置超时参数，辅以net.DialTimeout直连测试网络连通性。
XORM框架运行时报错，常见于数据库连接失败、查询卡死或初始化异常，多数由驱动未注册或连接超时引发，直接导致程序panic或空指针崩溃。
检查数据库驱动是否已正确导入
第一步：确认import语句中是否包含驱动初始化行，例如MySQL必须有_ "github.com/go-sql-driver/mysql"这一行，且不能写成"github.com/go-sql-driver/mysql"（去掉下划线会编译通过但运行时无驱动）。
第二步：执行go mod tidy，确保go.sum中存在对应驱动的校验条目；若缺失，手动运行go get github.com/go-sql-driver/mysql@v1.7.1（推荐v1.7.1及以上兼容XORM v1.3+）。
第三步：在main()函数最开头插入测试代码：_, ok := sql.Drivers()["mysql"]; fmt.Println("MySQL驱动注册状态:", ok)。如果输出false，说明驱动未生效——【必须重启go run或重新构建二进制】，热加载无法补注册。
排查连接超时与网络阻塞
方法一：显式设置超时参数
在DSN字符串末尾追加&timeout=5s&readTimeout=10s&writeTimeout=10s，例如："root:pass@tcp(127.0.0.1:3306)/test?charset=utf8mb4&timeout=5s&readTimeout=10s"。注意&是HTML实体，在Go字符串中应写作&，否则解析失败。
方法二：用xorm.NewEngineWithContext传入带超时的context
替换原NewEngine调用：ctx, cancel := context.WithTimeout(context.Background(), 8*time.Second); defer cancel(); engine, err := xorm.NewEngineWithContext(ctx, "mysql", dsn)。这能强制中断卡在TCP握手或DNS解析阶段的连接尝试，避免goroutine永久挂起。
方法三：验证底层网络连通性
不依赖XORM，用原生net.DialTimeout("tcp", "127.0.0.1:3306", 3*time.Second)直连端口。如果这里就超时，说明是防火墙、MySQL服务未启动或地址配置错误——【XORM报错信息里不会提示这类底层问题，必须手动剥离验证】。
定位SQL执行超时的具体语句
启用XORM日志并过滤慢查询：
在engine初始化后添加：engine.ShowSQL(true); engine.Logger().SetLevel(xorm.LOG_DEBUG)，然后重定向日志到文件：engine.SetLogger(xorm.NewSimpleLogger(os.Stdout))。
运行程序，复现报错，从日志中找到最后一条成功打印的SQL，再看下一条是否卡住超过设定timeout值。若某条SELECT * FROM users WHERE id = ?耗时7秒而你设了5秒超时，就锁定该语句需优化索引或改写逻辑。
注意：日志开启后性能下降明显，仅用于调试，上线前务必关闭ShowSQL。
