必须确认vs code中launch.json的"program"字段指向v2版autohotkey.exe真实路径，且需同时安装ahk++与vscode-autohotkey-debug插件并重启编辑器。
确认 AutoHotkey v2 运行时路径是否正确
VS Code 调试 AHK 的前提是它能找到 AutoHotkey.exe。如果你装的是便携版、自定义路径，或同时有 v1 和 v2，launch.json 里不显式指定路径，调试会直接失败，报错类似：Cannot find AutoHotkey.exe 或 spawn AutoHotkey.exe ENOENT。
打开项目根目录下的 .vscode/launch.json，检查 "program" 字段是否指向真实可执行文件（不是脚本）：
{
"version": "0.2.0",
"configurations": [
{
"type": "autohotkey",
"request": "launch",
"name": "调试AHK脚本",
"program": "C:\Program Files\AutoHotkey\AutoHotkey.exe",
"args": ["${file}"]
}
]
}
- 路径中不能含中文或空格（若含，用双引号包裹）
- 务必用 v2 版本的
AutoHotkey.exe（v1 的不兼容调试协议） - 如果使用 Ahk2Exe 编译过，别误把
Compiler.exe当成运行时
安装并启用两个关键插件：AHK++ 和 vscode-autohotkey-debug
只装一个插件是不够的——AHK++（Mark Wiemer 版）负责语法高亮、补全、错误提示；vscode-autohotkey-debug 才提供断点、变量监视、单步执行等调试能力。两者缺一不可，且必须按顺序安装：先 AHK++，再 vscode-autohotkey-debug，否则后者可能无法识别语言模式。
- 插件名必须完全匹配：
ahk-plus-plus和zero-plusplus.vscode-autohotkey-debug - 安装后重启 VS Code，否则调试按钮（虫子图标）可能灰掉
- 确保当前文件后缀为
.ahk，且右下角状态栏显示语言模式是AutoHotkey（不是 Plain Text）
调试时常见断点失效或跳过的原因
AHK v2 的调试协议对语句结构敏感，以下写法会导致断点“看似生效”但实际不暂停：
- 在函数定义行（
MyFunc() {）设断点——无效，断点需落在函数体内部第一行可执行语句上 - 在注释行、空行、
#Requires指令行设断点——跳过 - 脚本开头没加
#NoEnv或#Warn，而运行时因环境变量解析失败提前退出——断点根本没机会触发 - 使用了
Hotkey动态注册（如Hotkey, ^a, MyLabel），但断点设在MyLabel:标签行——需在标签后的首条语句设断点
验证是否真进入调试：在断点前加一句 MsgBox "debug start"，看弹窗是否出现。
运行脚本比调试更简单，但要注意编码和参数传递
想快速运行（非调试），推荐用 Code Runner 插件配置 executorMap，比手动敲命令更可靠：
"code-runner.executorMap": {
"ahk": ""C:\Program Files\AutoHotkey\AutoHotkey.exe" /CP65001 "${file}""
}
-
/CP65001强制 UTF-8 编码，避免中文乱码（尤其含 MsgBox 或 FileRead 时） - 不要漏掉
"${file}"—— 否则脚本不会被传给解释器 - 若脚本依赖相对路径（如
FileRead, content, ./data.txt），运行时工作目录默认是文件所在目录，不是 VS Code 打开的文件夹根目录
真正复杂的逻辑（比如涉及 GUI、热键监听、多线程模拟）必须进调试模式看变量实时值——靠 MsgBox 或日志输出太慢，也容易干扰流程。调试器里鼠标悬停看变量、Watch 面板输表达式、Call Stack 查调用链，这些才是定位问题的核心手段。
