写 AHK 最耗时的不是写代码,是排查为什么没反应。
这篇把调试方法系统化:先判断属于哪类失败,再用对应手段定位。文中所有方法都在 v2 上验证过。
一、先分类:三种失败形态
| 形态 | 表现 | 优先怀疑 |
|---|---|---|
| ① 报错弹窗 | 明确提示某行出错 | 语法、变量未定义、对象为空 |
| ② 静默失败 | 脚本跑起来了,但什么都没发生 | 热键没生效、目标窗口没找到、权限不足 |
| ③ 行为不对 | 动了,但结果不是你要的 | 坐标、时序、编码、条件判断 |
三种形态的排查路径完全不同。先用 30 秒判断属于哪一类,能省掉一半时间。
二、让错误”说出来”(对应形态 ①)
1. 用 try/catch 抓住它
try {
result := SomeRiskyCall()
} catch as e {
MsgBox "出错:`n" e.Message "`n位置:" e.File " 第 " e.Line " 行`n额外:" e.Extra
}
e.Extra 常常直接告诉你真正的原因(比如”参数类型不对”)。
2. 全局兜底
OnError(Handler)
Handler(err, mode) {
FileAppend FormatTime(, "yyyy-MM-dd HH:mm:ss") " [ERROR] "
. err.Message " @ " err.File ":" err.Line "`n"
, A_ScriptDir "error.log", "UTF-8"
return 1 ; 1 = 已处理,不弹默认对话框
}
3. 编译后的 exe 也能看到错误
用 Ahk2Exe 时加参数 /ErrorStdOut,错误会输出到标准错误,便于在命令行里查看。
三、静默失败怎么查(对应形态 ②)
第一步:确认热键到底有没有被触发
^!t:: {
ToolTip "热键触发了"
SetTimer () => ToolTip(), -1500
}
连提示都不出 → 热键没注册上,常见原因:
- 脚本没运行(看托盘图标)
- 另一个程序抢占了同一热键(换一个组合测试)
- 脚本运行在管理员上下文,而快捷键在前台普通进程里(UIPI 隔离)→ **用管理员身份运行脚本**
- 用了
#IfWinActive但窗口标题不匹配
第二步:确认目标窗口找到了
hwnd := WinExist("ahk_exe chrome.exe")
if !hwnd {
MsgBox "没找到窗口"
return
}
MsgBox "窗口标题:" WinGetTitle(hwnd) "`n客户区:" WinGetClientPos(&x, &y, &w, &h, hwnd)
标题里带特殊字符、窗口最小化、多显示器坐标偏移,都会导致”找到了但操作不到”。
第三步:确认坐标换算对不对
; 打点:把要点击的位置画出来看
CoordMode "Mouse", "Screen"
MouseMove 500, 300
Sleep 300
MsgBox "鼠标现在在 (" A_CaretX ") 附近吗?"
最常见的原因是 DPI 缩放:屏幕设了 125%,逻辑坐标和物理坐标差 1.25 倍。开头加 DllCall("SetProcessDPIAware")。
四、行为不对怎么查(对应形态 ③)
关键位置打日志
Log(msg) {
FileAppend FormatTime(, "HH:mm:ss.fff") " " msg "`n", A_ScriptDir "debug.log", "UTF-8"
}
Log("开始处理:" file)
Log("读到内容长度:" StrLen(txt))
Log("即将点击:" x "," y)
Click x, y
Log("点击完成")
日志比断点好用——因为它能留下时序信息,能看出”是不是点击太快、界面还没刷新”。
时序问题的标准解法
; 别用固定 Sleep,等条件成立
WaitFor(cond, timeoutMs := 5000) {
t0 := A_TickCount
while (A_TickCount - t0 < timeoutMs) {
if cond()
return true
Sleep 100
}
return false
}
; 用法:等窗口出现
if !WaitFor(() => WinExist("ahk_exe notepad.exe"), 5000)
MsgBox "5 秒内没等到记事本"
五、二分法:代码长的时候最快的办法
300 行的脚本不知道哪一步挂了:
- 在中间插一句
MsgBox "到这里了" - 弹出来了 → 问题在后半段;没弹 → 问题在前半段
- 重复,10 次以内定位到具体行
比读代码快得多,尤其对付别人的脚本。
六、十个高频报错逐条解读
| 报错信息 | 真实原因 | 怎么修 |
|---|---|---|
| Error: This value of type “Integer” has no method | 把数字当对象用了 | 检查变量是不是被覆盖 |
| Error: Variable not initialized | 变量没赋值就用了 | 加默认值或先赋值 |
| Error: Expected a Number | 传了字符串给要数字的参数 | 加 +0 强制转数字 |
| Error: Call to nonexistent function | 函数名拼错或没 Include | 检查大小写与 #Include |
| Error: Missing “}” | 括号不配对 | 从报错行往上找 |
| Error: Target window not found | 窗口标题/进程名不对 | 用 Window Spy 重新取 |
| Error: Invalid GUI control | 控件名写错或还没创建 | 确认 vName 与引用一致 |
| Error: 0x80070005 (Access denied) | 权限不足 | 用管理员运行 |
| Error: 0x80004005 | COM 对象调用失败 | 检查目标程序是否装了/开着 |
| 静默无反应(无报错) | 热键冲突 / UIPI / 脚本未运行 | 见第三节 |
七、环境类问题(最容易误判成”代码错了”)
- 管理员 vs 普通权限:脚本在管理员上下文,无法向普通权限的窗口发送输入(UIPI)。要么都提权,要么都用普通权限
- UAC 弹窗:UAC 界面在安全桌面上,普通脚本碰不到
- 输入法:中文输入法激活时,
Send发的字符可能被输入法吃掉 → 先Send "{vk15sc138}"切英文,或直接用SendText - DPI:见第三节
- 远程桌面:RDP 断开后,GUI 交互全部失效(没有活动会话)
- 杀软:静默拦截 SendInput/模拟点击,日志里看不出来
八、调试工具三件套
- Window Spy(AHK 自带):取窗口标题、进程名、控件信息、鼠标坐标
- DebugView(微软 Sysinternals):捕获
OutputDebug输出,不弹窗 - Acc Viewer(UIA 检查器):看控件树,判断能不能用 UIA 而不是坐标
用 OutputDebug 打点:
OutputDebug "步骤 1 完成,用时 " (A_TickCount - t0) "ms"
九、排查清单(照着走)
- □ 脚本在运行吗?(托盘图标)
- □ 热键被别的程序占了吗?(换个组合试)
- □ 权限一致吗?(脚本 vs 目标窗口)
- □ 窗口标题/进程名对吗?(Window Spy)
- □ 需要先激活窗口吗?(
WinActivate+ 等待) - □ 坐标是屏幕坐标还是窗口坐标?(
CoordMode) - □ DPI 缩放设了吗?
- □ 有时序问题吗?(改用等条件,不用固定 Sleep)
- □ 输入法影响输入了吗?(
SendText) - □ 杀软拦截了吗?(加白名单测试)
这套方法配合工具包的日志与错误处理模板,能把大部分问题在几分钟内定位。AI 自动化工具包里有可直接引用的 Log()、OnError、WaitFor() 封装;企业里要排查多台机器的问题,可以留个联系方式。

