3000 字
15 分鐘
用 Python 寫 AutoHotkey 腳本：Windows 自動化入門教學
2026-04-18
2026-10-26
電腦雜七雜八
Python
/
AutoHotkey
/
自動化腳本

每天操作 Windows，總有一些步驟會一直重複：打開程式、切換視窗、輸入固定文字，或把資料一筆筆填進表單。步驟不難，做多了卻很花時間。

AutoHotkey 可以操作滑鼠、鍵盤和視窗。搭配 Python 的 ahk 套件，就能用熟悉的 Python 語法安排這些動作，再接上檔案處理、日期計算或其他套件。例如，先讀取 CSV，再把資料輸入桌面程式。

這篇從安裝開始，先讀取滑鼠位置，接著操作記事本，最後做一個按 F8 就能輸入時間的快捷鍵工具。範例使用 Windows、Python ahk 1.8.4 與 AutoHotkey v2，程式檔請儲存為 UTF-8。

Python、ahk 與 AutoHotkey 的關係#

這裡有三個不同的東西：

名稱負責的工作
Python撰寫流程、條件判斷、迴圈與資料處理
ahk 套件提供 Python 介面，將操作交給 AutoHotkey
AutoHotkey 執行檔實際執行 Windows 滑鼠、鍵盤及視窗操作

因此，只安裝 Python 套件不一定就有執行引擎。下面採用專案提供的 binary 額外依賴，一起準備需要的 AutoHotkey 執行檔。ahk 專案的安裝說明（在新分頁開啟）

如果流程需要操作網頁元素、等待網頁載入或下載檔案，通常先考慮瀏覽器自動化工具。這篇著重在 Windows 桌面程式，會用記事本當練習對象。

安裝與環境設定#

建立獨立的練習目錄#

先安裝 Python（在新分頁開啟），再開啟 PowerShell。ahk 1.8.4 的套件需求是 Python 3.8 以上；實際安裝前也要確認所選 Python 版本仍適合自己的開發環境。套件版本與需求（在新分頁開啟）

下面使用新的練習目錄，避免和其他專案的套件混在一起：

Terminal window
mkdir python-ahk-demo
cd python-ahk-demo
py -m venv .venv
.\.venv\Scripts\python.exe -m pip install "ahk[binary]==1.8.4"

後面的指令都直接使用虛擬環境裡的 python.exe，不必先執行 Activate.ps1，也不需要為了啟用環境更改 PowerShell 執行原則。Python venv 文件（在新分頁開啟）

本文會陸續建立以下檔案：

python-ahk-demo/
├── .venv/
├── hello_ahk.py       # 確認環境，讀取滑鼠位置
├── mouse_demo.py      # 移動滑鼠
├── notepad_demo.py    # 找到記事本並輸入文字
├── hotkey_demo.py     # F8 輸入時間，F9 結束
└── image_demo.py      # 選讀：尋找螢幕上的圖片

明確指定 AutoHotkey v2#

每個範例都會使用：

from ahk import AHK


ahk = AHK(version="v2")

這個設定讓套件尋找 v2 執行檔，並檢查版本。原本的 AHK() 沒有指定版本，可能找到 v1；如果把兩個版本的原生腳本語法混用，就容易遇到錯誤。ahk 的 v2 設定說明（在新分頁開啟）

如果你已經自行安裝 AutoHotkey，也可以只安裝 ahk==1.8.4，並明確指定執行檔。以下路徑必須依實際安裝位置調整：

from ahk import AHK


ahk = AHK(
    version="v2",
    executable_path=r"C:\Program Files\AutoHotkey\v2\AutoHotkey64.exe",
)

兩種安裝方式選一種即可。不要把 .ahk 腳本檔或 AutoHotkey 安裝程式填進 executable_path。

第一個程式：讀取滑鼠位置#

建立 hello_ahk.py：

from importlib.metadata import version


from ahk import AHK




def main():
    ahk = AHK(version="v2")
    x, y = ahk.get_mouse_position(coord_mode="Screen")
    print(f"ahk 套件版本：{version('ahk')}")
    print(f"滑鼠螢幕座標：x={x}, y={y}")




if __name__ == "__main__":
    main()

執行：

Terminal window
.\.venv\Scripts\python.exe hello_ahk.py

如果能印出版本與座標，代表 Python 已經能透過套件呼叫 AutoHotkey。這個程式只讀取位置，不會移動滑鼠或輸入文字。

座標要先選好基準#

同一個 (100, 100)，可能是相對於整個螢幕，也可能是相對於目前視窗。

座標模式基準
Screen螢幕座標，適合先記錄再移動到固定位置
Window作用中視窗的左上角，包含視窗邊框等區域
Client作用中視窗的用戶端區域，排除標題列與邊框等非用戶端區域

本文的滑鼠與圖片範例都明確指定 Screen。主螢幕左上角通常是 (0, 0)，往右 x 增加、往下 y 增加；多螢幕配置可能出現負座標。記錄座標和執行動作時，必須使用相同基準。AutoHotkey CoordMode 說明（在新分頁開啟）

移動滑鼠與點擊#

建立 mouse_demo.py。程式會先等待三秒，再把滑鼠移到螢幕座標 (300, 300)：

import time


from ahk import AHK


ahk = AHK(version="v2")


print("三秒後移動滑鼠，不會點擊。")
time.sleep(3)


ahk.mouse_move(
    x=300,
    y=300,
    coord_mode="Screen",
    blocking=True,
)


print("目前座標：", ahk.get_mouse_position(coord_mode="Screen"))

blocking=True 表示等這次操作完成，再執行下一行 Python。它不是等待秒數，也不會替你等候目標程式載入。

需要點擊時，可以在移動之後加入：

# 接在 mouse_demo.py 的 ahk.mouse_move(...) 後面。
# 先確認這個位置是可以點擊的測試區域，再取消下一行的註解。
# ahk.click(x=300, y=300, coord_mode="Screen")

滑鼠移到哪裡、點到哪裡，都和視窗位置、解析度及顯示縮放有關。第一次測試先只移動，位置正確後再加入點擊。

speed 不是幾秒鐘#

AutoHotkey 的移動速度參數使用 0 到 100 的範圍，0 是立即移動，數字越大越慢。speed=10 不代表移動十秒。 v2 預設的 Input 傳送模式還會忽略這個速度參數。MouseMove 官方說明（在新分頁開啟）

如果要觀察較慢的移動，可以明確選用 Event 模式：

from ahk import AHK


ahk = AHK(version="v2")
ahk.mouse_move(
    x=300,
    y=300,
    speed=20,
    send_mode="Event",
    coord_mode="Screen",
    blocking=True,
)

要在兩個步驟之間停一秒，請用 time.sleep(1)；要等視窗出現，則使用下一節的視窗等待方法。

完整範例：找到記事本並輸入文字#

直接傳送按鍵時，文字會送到當下有焦點的輸入位置。比較容易排查的流程是：先找到指定程式，切到該視窗，確認啟用後再輸入。

先手動開啟一個空白記事本，測試時只留一個記事本視窗／空白分頁，避免找到其他文件。回到 PowerShell 後，執行以下 notepad_demo.py：

from ahk import AHK




def main():
    ahk = AHK(version="v2")
    input("請先開啟空白記事本，再回到這裡按 Enter：")


    try:
        window = ahk.win_wait(title="ahk_exe notepad.exe", timeout=10)
        window.activate()
        ahk.win_wait_active(title=f"ahk_id {window.id}", timeout=5)
    except TimeoutError:
        print("等不到記事本啟用，請確認記事本已開啟後再試一次。")
        return


    ahk.type("這段文字是 Python 透過 AutoHotkey 輸入的。")
    ahk.key_press("Enter")
    ahk.type("下一步可以接上檔案讀取或資料整理流程。")
    print("輸入完成。請到記事本檢查結果。")




if __name__ == "__main__":
    main()
Terminal window
.\.venv\Scripts\python.exe notepad_demo.py

這裡用 ahk_exe notepad.exe 找程式，再用 ahk_id 鎖定找到的視窗，不需要把中文或英文的「未命名」視窗標題寫死。win_wait 與 win_wait_active 分別等候視窗出現、視窗成為作用中視窗，並設定逾時時間。視窗 API 文件（在新分頁開啟）

這種前景輸入方式仍需要正確的編輯區焦點。執行期間如果切到別的程式，後續輸入可能送錯位置；實際流程也應在關鍵步驟重新確認目標。

輸入文字與傳送快捷鍵#

ahk.type() 適合輸入一般文字；需要快捷鍵或特殊按鍵時，使用 send_input() 或 key_press()。以下是可接在前面記事本範例中的操作片段，請一次選一種測試：

# 一般文字：+、!、^ 會作為文字處理。
ahk.type("測試文字：1 + 1 = 2，符號包含 ! ^ #")


# 特殊按鍵。
ahk.key_press("Enter")
ahk.key_press("Tab")


# Ctrl+End：將游標移到文件最後。
ahk.send_input("^{End}")

在傳送按鍵的語法裡，^ 是 Ctrl、! 是 Alt、+ 是 Shift、# 是 Windows 鍵。一般文字如果混用這些控制符號，容易得到和預期不同的結果。鍵盤操作範例（在新分頁開啟）

需要移動或縮放剛剛找到的記事本視窗，也可以在同一個範例裡使用：

window.move(x=100, y=100, width=800, height=500)

實用小工具：按 F8 輸入目前時間#

下面把前面的輸入動作包成快捷鍵。執行後不會立刻打字，按下 F8 才觸發；只有目前作用中的程式是記事本時，才會輸入日期時間。F9 用來結束工具。

建立 hotkey_demo.py：

from datetime import datetime
from threading import Event


from ahk import AHK


ahk = AHK(version="v2")
stop_event = Event()




def insert_timestamp():
    window = ahk.win_get(title="A")
    if window.get_process_name().lower() != "notepad.exe":
        print("請先切到記事本的空白編輯區，再按 F8。")
        return


    timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
    ahk.type(timestamp)




ahk.add_hotkey("F8", callback=insert_timestamp)
ahk.add_hotkey("F9", callback=stop_event.set)
ahk.start_hotkeys()


print("切到記事本後按 F8 輸入時間，按 F9 結束。")


try:
    while not stop_event.wait(0.2):
        pass
except KeyboardInterrupt:
    print("收到 Ctrl+C，準備結束。")
finally:
    ahk.stop_hotkeys()
    print("快捷鍵已停止。")
Terminal window
.\.venv\Scripts\python.exe hotkey_demo.py

start_hotkeys() 會啟動處理快捷鍵的程序；主程式也必須保持執行，不能註冊完就直接結束。這裡用 Event 等待結束訊號，並在 finally 停止快捷鍵。停止快捷鍵不會強制中斷已經開始執行的回呼，因此先讓每次操作維持短而單純。快捷鍵生命週期說明（在新分頁開啟）

F8、F9 是全域快捷鍵，程式執行期間會攔截這兩個按鍵。如果和常用軟體衝突，可以改成 ^!p、^!q，分別代表 Ctrl+Alt+P、Ctrl+Alt+Q。

選讀：用圖片尋找位置#

按鈕位置經常改變時，可以先用圖片找位置，再決定下一個動作。ahk 本身有 image_search()；想做更複雜的影像處理，再考慮搭配 OpenCV。

先從目前畫面截下一小塊容易辨認的按鈕，存成 button.png，和 image_demo.py 放在一起。下面只列出結果，不會自動點擊：

from pathlib import Path


from ahk import AHK


image_path = Path(__file__).resolve().with_name("button.png")
if not image_path.is_file():
    raise SystemExit("請先把測試用的 button.png 放在程式旁邊。")


ahk = AHK(version="v2")
position = ahk.image_search(
    str(image_path),
    coord_mode="Screen",
)


if position is None:
    print("畫面上找不到這張圖片。")
else:
    x, y = position
    print(f"找到圖片左上角：x={x}, y={y}")

image_search() 找不到圖片會回傳 None；找到時回傳的是圖片左上角，不是按鈕中心。若圖片無法讀取，則需要另外排查檔案或執行錯誤。圖片搜尋 API（在新分頁開啟）

截圖和執行時的顯示縮放、程式主題或按鈕大小不同，都可能影響辨識。先用同一台電腦、同一個畫面測試，確認能找到目標，再限制搜尋範圍或調整辨識方式。

常見問題#

出現 ModuleNotFoundError: No module named ‘ahk’#

通常是安裝套件與執行程式用了不同的 Python。改用同一個虛擬環境執行檔檢查：

Terminal window
.\.venv\Scripts\python.exe -m pip show ahk
.\.venv\Scripts\python.exe hello_ahk.py

也不要把自己的檔案命名為 ahk.py，以免蓋過真正的套件。

找不到 AutoHotkey 執行檔，或提示版本不符#

先確認是否安裝了 ahk[binary]，以及程式是否使用 AHK(version="v2")。自行安裝引擎時，檢查 executable_path 是否指向實際的 v2 執行檔；如果曾設定 AHK_PATH，也要確認它沒有仍指向舊版本。

滑鼠位置不對，或文字沒有輸入#

依序檢查：

  • 取得座標和執行動作時，是否都使用相同的 coord_mode。
  • 螢幕解析度、顯示縮放或視窗位置是否改變。
  • 目標視窗是否已啟用，編輯區是否有焦點，是否還在載入。
  • 目標程式與 Python 的執行權限是否一致；不要把升高權限當作每個問題的第一個解法。

若程式可以直接讀取檔案或呼叫 API，優先使用那些介面，通常比依賴滑鼠座標穩定。只有必須操作畫面的部分，再交給 AutoHotkey。

快捷鍵程式啟動後馬上結束#

檢查是否呼叫 start_hotkeys()，並且保留等待迴圈。停止快捷鍵只負責移除這些快捷鍵，不應拿來當作終止任意長時間工作的方法；需要長流程時，讓迴圈定期檢查自己的停止旗標。

可以用在遊戲嗎？#

能否接收模擬輸入會依程式而異，ahk 不保證支援所有遊戲。若要用在遊戲或第三方服務，先確認該服務對自動化操作的規定；本文的範例以自己的 Windows 桌面與記事本練習為主。

延伸閱讀#

用 Python 寫 AutoHotkey 腳本：Windows 自動化入門教學
https://aishuafei.com/posts/用python-寫autohotkey-腳本/
作者
愛耍廢
發佈於
2026-04-18
更新於
2026-10-26
許可協議
CC BY-NC-SA 4.0
Python 開發的按鍵精靈：Airtest Project 筆記
離線下載使用Drive、aria2、colab
© 2026 愛耍廢. All Rights Reserved. / RSS / Sitemap
Powered by Astro & Fumika