必须同时安装ahk++和vscode-autohotkey-debug插件，且launch.json中"program"字段须明确指向v2版autohotkey.exe真实路径（如c:program filesutohotkey 2utohotkey.exe），路径含空格或中文需加双引号，不可用"${file}"或v1/ahk2exe.exe；调试前须确认文件后缀为.ahk且右下角语言模式显示“autohotkey”。
必须装 AHK++ 和 vscode-autohotkey-debug 两个插件，缺一不可；launch.json 中的 program 字段必须指向 v2 版本的 AutoHotkey.exe 真实路径，否则调试按钮始终灰掉、断点完全不生效。
确认 AutoHotkey v2 解释器路径是否正确
VS Code 调试依赖能真正执行脚本的解释器，不是编译器，也不是 v1 的 exe。常见错误是：launch.json 里写成 "program": "AutoHotkey.exe"（没路径）、"program": "Ahk2Exe.exe"（这是编译工具）、或指向了 v1 安装目录下的 AutoHotkey.exe。
- 打开命令行，运行
where AutoHotkey.exe（Windows）或Get-Command AutoHotkey.exe | Select-Object -ExpandProperty Path（PowerShell），确认输出的是 v2 路径，例如C:Program FilesAutoHotkey 2AutoHotkey.exe - 若安装的是便携版，路径含空格或中文（如
D:我的工具AHK 2AutoHotkey.exe），必须用双引号包裹，且不能漏掉.exe后缀 - 检查
AutoHotkey.exe文件属性 → “详细信息”标签页 → “产品版本”是否为2.x.x，v1 显示的是1.1.x
安装并启用两个关键插件：AHK++ 和 vscode-autohotkey-debug
只装一个插件，调试功能就等于没开。AHK++（全名 ahk-plus-plus）负责语言识别、语法高亮、#Requires AutoHotkey v2.0 校验和基础补全；vscode-autohotkey-debug（ID：zero-plusplus.vscode-autohotkey-debug）才提供断点、变量监视、单步执行等能力。
- 必须按顺序安装：先搜
ahk-plus-plus并启用，重启 VS Code；再搜vscode-autohotkey-debug并启用，再次重启 - 重启后打开任意
.ahk文件，右下角状态栏应显示AutoHotkey（不是Plain Text），且编辑器左上角调试面板中出现调试AHK脚本配置项 - 如果调试按钮（虫子图标）仍是灰色，大概率是语言模式未识别成功——检查文件后缀是否为
.ahk，且首行是否有#Requires AutoHotkey v2.0
配置 launch.json 时避开三个典型陷阱
VS Code 的调试行为高度依赖 .vscode/launch.json 内容，以下写法看似合理，实际会导致“启动失败”“跳过断点”或“中文乱码”：
-
"program": "${file}"—— 错误。这会让调试器尝试把脚本本身当解释器执行，报错spawn ${file} ENOENT；必须明确写成"program": "C:\path\to\AutoHotkey.exe" -
"args": ["${file}"]单独存在但没加/CP65001—— 中文 MsgBox 或 FileRead 会显示方块或乱码；建议统一写成"args": ["/CP65001", "${file}"] - 断点设在热键定义行（如
^!t::）或标签行（如MyLabel:）—— AHK v2 调试协议只在可执行语句处暂停；断点应设在标签后的第一行代码，比如MsgBox "hello"
快速运行脚本比调试更常用，推荐用 Code Runner 统一管理
日常开发中，90% 场景只需“保存即运行”，无需进调试界面。Code Runner 插件配合自定义 executorMap 更稳定、编码更可控。
- 安装
Code Runner插件后，在设置中搜索code-runner.executorMap，添加如下配置：
"code-runner.executorMap": {
"ahk": ""C:\Program Files\AutoHotkey\v2\AutoHotkey.exe" /CP65001 "${file}""
}
.ahk 文件右键 → “Run Code”，或按快捷键 Ctrl+Alt+N，即可带 UTF-8 编码直接运行launch.json，调试仍走 F5 流程，两者互不影响最常被忽略的一点：所有配置生效的前提是当前文件被 VS Code 正确识别为 AHK 语言模式。哪怕路径、插件、JSON 全对，只要右下角显示的是 Plain Text，断点和语法提示就永远不会触发——此时手动点击右下角文字，选择 Configure File Association for '.ahk' → AutoHotkey 即可修复。
