Automation on YuChen

如何使用 PyAutoGUI（一）：安裝與滑鼠控制

Thu, 30 Apr 2026 00:00:00 +0800

內容大綱

PyAutoGUI 基本介紹
安裝 PyAutoGUI
螢幕座標系統
安全機制：Fail-Safe
取得螢幕資訊
滑鼠點擊
滑鼠移動
滾輪操作
- 垂直滾動
- 水平滾動

1. PyAutoGUI 基本介紹

PyAutoGUI 是一個跨平台的 Python GUI 自動化套件，可以程式化地控制滑鼠與鍵盤，適用於 Windows、macOS 和 Linux。常見應用場景包括：

重複性操作自動化：自動填表、批次處理檔案。
GUI 測試：模擬使用者操作，進行介面測試。
螢幕截圖與圖像辨識：截圖並尋找特定圖案位置，再進行點擊。

⚠️ 注意事項
PyAutoGUI 會直接控制系統的滑鼠與鍵盤，執行時請先確認不會誤操作重要視窗，建議先在測試環境中嘗試。

2. 安裝 PyAutoGUI

在終端機輸入以下指令：

pip install pyautogui

若有多個版本的 python 可以指定特定版本：

py -3.8 -m pip install pyautogui

macOS：

python3 -m pip install pyautogui

Linux：
還需要安裝額外依賴套件。

sudo apt-get install python3-tk python3-dev scrot
python3 -m pip install pyautogui

安裝完成後，驗證是否成功：

import pyautogui
print(pyautogui.size()) # 印出螢幕解析度，例如 Size(width=1920, height=1080)

3. 螢幕座標系統

在開始自動化之前，我們必須先了解電腦螢幕的座標系統（Coordinate System）：

原點 (0, 0)：位於螢幕的 左上角 (Top-Left)。
X 軸：水平方向，由左向右遞增。
Y 軸：垂直方向，由上向下遞增。

如果你想更直觀地了解座標位置，可以使用下方我開發的小工具。移動滑鼠即可即時顯示座標，點擊畫面則可以釘選座標點。

互動小工具：螢幕座標地圖 建議點擊右上角的「全螢幕」按鈕或將瀏覽器視窗最大化，以獲得最準確的座標參考。
程式碼已開源於：screen-coordinate-map

4. 安全機制：Fail-Safe

PyAutoGUI 內建一個防呆安全機制：當滑鼠快速移動到螢幕左上角（座標 0, 0）時，會自動丟出 FailSafeException 並中止程式。

這個機制可以讓你在程式失控時，快速移動滑鼠到左上角以強制停止。

import pyautogui

# 安全機制，正式使用時請保持啟用（預設為 True）
pyautogui.FAILSAFE = True

# 若確定不需要此機制（不建議）可關閉
pyautogui.FAILSAFE = False

此外，還有一個全域延遲設定，讓每個操作之間自動暫停，避免操作太快：

# 每次 PyAutoGUI 函式呼叫後，暫停 0.5 秒（預設為 0.1）
pyautogui.PAUSE = 0.5

5. 取得螢幕資訊

import pyautogui

# 取得螢幕解析度
width, height = pyautogui.size()
print(f"螢幕寬度：{width}，高度：{height}")

# 取得滑鼠目前位置
x, y = pyautogui.position()
print(f"目前滑鼠座標：({x}, {y})")

💡 小技巧：執行以下程式碼，可以即時追蹤滑鼠座標，按 Ctrl+C 停止：

import pyautogui, time
try:
 while True:
 x, y = pyautogui.position()
 print(f"\r目前座標：({x:4}, {y:4})", end="", flush=True)
 time.sleep(0.1)
except KeyboardInterrupt: # 按下 Ctrl+C 會中斷程式
 print("\n已停止追蹤")

6. 滑鼠點擊

點擊 `click()`：

import pyautogui

pyautogui.click() # 在目前位置點擊左鍵

pyautogui.click(500, 300) # 點擊指定座標

pyautogui.click(500, 300, button='right') # 指定按鍵 'left'、'right'、'middle'

pyautogui.click(500, 300, clicks=2) # 連續點擊
pyautogui.click(500, 300, clicks=2, interval=0.25) # 設定兩次點擊之間的間隔（秒）
pyautogui.click(button='right', clicks=3, interval=0.25) # 指定按鍵並連續點擊

雙擊 `doubleClick()`：

# 在指定位置雙擊
pyautogui.doubleClick(500, 300)

註解
也有 tripleClick() 函數，用以點擊三次螢幕。

右鍵點擊 `rightClick()`：

pyautogui.rightClick(500, 300)

中鍵點擊 `middleClick()`：

pyautogui.middleClick(500, 300)

分開按下與放開 `mouseDown()` / `mouseUp()`：

# 按下與放開皆預設為左鍵
pyautogui.mouseDown() # 按下左鍵（不放開）
pyautogui.mouseUp() # 放開左鍵

# 按下右鍵（不放開）
pyautogui.mouseDown(500, 300, button='right')

# 放開右鍵
pyautogui.mouseUp(500, 300, button='right')

7. 滑鼠移動

移動到絕對座標 `moveTo(x, y, duration=num_seconds)`：

import pyautogui

# 移動到螢幕座標 (500, 300)
pyautogui.moveTo(500, 300)

# 移動到 (500, 300)，花費 1 秒（加入緩動效果）
pyautogui.moveTo(500, 300, duration=1)

# 使用緩動函式（easing），讓動作更自然
pyautogui.moveTo(500, 300, duration=1, tween=pyautogui.easeInOutQuad)

移動到相對座標 `moveRel(xOffset, yOffset, duration=num_seconds)`：

# 從目前位置，向右移動 100px、向下移動 50px
pyautogui.moveRel(100, 50)

# moveRel 與 move 完全相同
pyautogui.move(100, 50, duration=0.5)

拖曳到絕對座標 `dragTo(x, y, duration=num_seconds)`：

import pyautogui

# 從目前位置拖曳到 (700, 400)，花費 0.5 秒
pyautogui.dragTo(700, 400, duration=0.5)

# 指定使用左鍵拖曳
pyautogui.dragTo(700, 400, duration=0.5, button='left')

拖曳到相對座標 `dragRel(xOffset, yOffset, duration=num_seconds)`：

# 從目前位置向右拖曳 200px、向下 100px
pyautogui.dragRel(200, 100, duration=0.5)

# drag 與 dragRel 完全相同
pyautogui.drag(200, 100, duration=0.5)

實用範例：拖曳視窗

import pyautogui
import time

# 點擊視窗標題列(假設(400, 30)有視窗標題)
pyautogui.click(400, 30)
time.sleep(0.2)

# 拖曳視窗到新位置
pyautogui.dragTo(800, 200, duration=1, button='left')

常用 tween 緩動函式：

函式	效果	範例指令
`pyautogui.linear`	等速移動（預設）	`pyautogui.moveTo(x, y, tween=pyautogui.linear)`
`pyautogui.easeInQuad`	由慢到快	`pyautogui.moveTo(x, y, tween=pyautogui.easeInQuad)`
`pyautogui.easeOutQuad`	由快到慢	`pyautogui.moveTo(x, y, tween=pyautogui.easeOutQuad)`
`pyautogui.easeInOutQuad`	先慢後快再慢	`pyautogui.moveTo(x, y, tween=pyautogui.easeInOutQuad)`
`pyautogui.easeInBounce`	到達目標後反彈	`pyautogui.moveTo(x, y, tween=pyautogui.easeInBounce)`

8. 滾輪操作

垂直滾動 `scroll()`

import pyautogui

# 向上滾動 3 格（正值向上，負值向下）
pyautogui.scroll(3)

# 在指定座標向下滾動 5 格
pyautogui.scroll(-5, x=500, y=400)

水平滾動 `hscroll()`

# 向右水平滾動 3 格
pyautogui.hscroll(3)

# 向左水平滾動 3 格
pyautogui.hscroll(-3)

練習題

📝 練習題 1：滑鼠畫正方形

題目：使用 moveTo() 讓滑鼠依序移動到四個角落，畫出一個邊長 200px 的正方形路徑（從座標 (200, 200) 出發）。

答案：

import pyautogui
import time

pyautogui.PAUSE = 0.5

pyautogui.moveTo(200, 200, duration=0.5)
pyautogui.moveTo(400, 200, duration=0.5)
pyautogui.moveTo(400, 400, duration=0.5)
pyautogui.moveTo(200, 400, duration=0.5)
pyautogui.moveTo(200, 200, duration=0.5)

print("正方形路徑完成！")

📝 練習題 2：自動右鍵選單

題目：在桌面空白處模擬右鍵點擊，然後按下 Escape 關閉選單（需搭配第二篇的鍵盤操作）。

答案：

import pyautogui
import time

time.sleep(2) # 給自己時間切換到桌面

# 在桌面中央右鍵點擊
screen_w, screen_h = pyautogui.size()
pyautogui.rightClick(screen_w // 2, screen_h // 2)
time.sleep(0.5)

# 按 Escape 關閉選單
pyautogui.press('escape')

📝 練習題 3：計算並移動到螢幕中心

題目：用程式取得螢幕解析度後，計算出螢幕中心點，並將滑鼠移動過去。

答案：

import pyautogui

width, height = pyautogui.size()
center_x = width // 2
center_y = height // 2

print(f"螢幕中心：({center_x}, {center_y})")
pyautogui.moveTo(center_x, center_y, duration=1)

參考資料

如何使用 PyAutoGUI（二）：鍵盤控制

Fri, 01 May 2026 19:20:00 +0800

內容大綱

文字輸入
單鍵操作
常用 Key 名稱對照表
訊息彈出視窗
- alert()
- confirm()
- prompt()
- password()
實用範例：自動開啟記事本並輸入文字

1. 文字輸入

`typewrite()` / `write()`

兩者完全相同，用於模擬逐鍵輸入文字：

import pyautogui

# 在目前焦點位置輸入文字
pyautogui.typewrite('Hello, World!')

# 設定每個字元之間的間隔（秒），模擬真實打字速度
pyautogui.typewrite('Hello!', interval=0.1)

# write() 與 typewrite() 完全相同
pyautogui.write('Python automation', interval=0.05)

⚠️ 注意：中文輸入限制
typewrite() 只支援 ASCII 字元，無法直接輸入中文。若要輸入中文，需改用剪貼簿方式：
import pyautogui
import pyperclip # pip install pyperclip

# 將中文複製到剪貼簿，再貼上
pyperclip.copy('你好，世界！')
pyautogui.hotkey('ctrl', 'v') # 稍後會介紹 hotkey 函數

2. 單鍵操作：

按下並放開單一按鍵 `press()`：

import pyautogui

# 按下 Enter 鍵
pyautogui.press('enter')

# 按下 Tab 鍵
pyautogui.press('tab')

# 按下方向鍵（上下左右）
pyautogui.press('up')
pyautogui.press('down')
pyautogui.press('left')
pyautogui.press('right')

# 連續按多次（按 3 次空白鍵）
pyautogui.press('space', presses=3)

# 設定每次按鍵之間的間隔
pyautogui.press('tab', presses=5, interval=0.2)

# 也可以傳入 list，依序按下多個鍵
pyautogui.press(['up', 'up', 'down', 'down', 'left', 'right'])

按住不放與放開按鍵 `keyDown()` / `keyUp()`：

import pyautogui

# 按住 Shift 鍵不放
pyautogui.keyDown('shift')

# 輸入文字（若無鎖定`CAPSLOCK`，此時會全部變大寫）
pyautogui.typewrite('hello') # 實際輸入 HELLO

# 放開 Shift 鍵
pyautogui.keyUp('shift')

實際應用：按住 Shift 並點擊以選取文字

import pyautogui
# 先點擊起始位置
pyautogui.click(200, 300)
# 按住 Shift
pyautogui.keyDown('shift')
# 點擊結束位置（選取這段範圍的文字）
pyautogui.click(600, 300)
# 放開 Shift
pyautogui.keyUp('shift')

上下文管理器 `hold()`：

import pyautogui

# 該shift鍵將在上下文區塊期間保持按住狀態。
with pyautogui.hold('shift'):
 pyautogui.press(['left', 'left', 'left'])

組合鍵與熱鍵 `hotkey()`：

import pyautogui

pyautogui.hotkey('ctrl', 'c') # Ctrl + C（複製）
pyautogui.hotkey('ctrl', 'v') # Ctrl + V（貼上）

# Alt + F4（關閉視窗，Windows）
pyautogui.hotkey('alt', 'f4')
# Ctrl + Alt + Delete（Windows）
pyautogui.hotkey('ctrl', 'alt', 'delete')
# macOS 截圖：Cmd + Shift + 4
pyautogui.hotkey('command', 'shift', '4')
# Ctrl + Shift + T（重開分頁，瀏覽器）
pyautogui.hotkey('ctrl', 'shift', 't')

3. 常用 Key 名稱對照表

以下是 press()、keyDown()、keyUp()、hotkey() 可接受的常用鍵名：

類別	Key 名稱
修飾鍵	`shift`、`ctrl`、`alt`、`command`（macOS）、`win`（Windows）
功能鍵	`f1` ~ `f12`
方向鍵	`up`、`down`、`left`、`right`
特殊鍵	`enter`、`esc`、`tab`、`backspace`、`delete`、`space`、`capslock`
Page 鍵	`pageup`、`pagedown`、`home`、`end`
數字鍵盤	`num0` ~ `num9`、`numlock`、`add`、`subtract`、`multiply`、`divide`
媒體鍵	`volumemute`、`volumedown`、`volumeup`、`playpause`
符號鍵	`!`、`@`、`#`、`$`、`%`、`^`、`&`、`*`、`(`、`)`
字母/數字	`a`～`z`、`0`～`9`

查看所有支援的鍵名：

import pyautogui
print(pyautogui.KEYBOARD_KEYS)

你也可以使用下方的互動式工具，快速搜尋按鍵名稱與對應的變數寫法：

互動小工具：鍵盤按鍵對照查詢 支援分類篩選與關鍵字搜尋，點擊按鍵卡片可產生範例程式碼。
程式碼已開源於：pynput-key-reference

4. 訊息彈出視窗

PyAutoGUI 提供了簡易的 GUI 彈出視窗函式，可在自動化流程中提示使用者或取得確認。

顯示訊息 `alert()`：

import pyautogui

# 顯示提示訊息
pyautogui.alert('操作完成！')

# 自訂標題
pyautogui.alert(text='備份成功。', title='通知', button='確定')

確認視窗 `confirm()`：

result = pyautogui.confirm('確定要刪除嗎？', title='確認', buttons=['確定', '取消'])
print(result) # 使用者點了哪個按鈕的文字

文字輸入視窗 `prompt()`：

name = pyautogui.prompt('請輸入你的名字：', title='輸入', default='')
if name:
 print(f'你好，{name}！')

密碼輸入視窗 `password()`（遮蔽顯示）：

pwd = pyautogui.password('請輸入密碼：', title='登入', default='', mask='*')
print(f'輸入的密碼：{pwd}')

5. 實用範例：自動開啟記事本並輸入文字

以下範例示範如何在 Windows 上自動開啟記事本，並輸入一段文字再儲存：

import pyautogui
import subprocess
import time

# 開啟記事本
subprocess.Popen(['notepad.exe'])
time.sleep(1.5) # 等待視窗開啟

pyautogui.press('shift') # 切換鍵盤成英文

# 輸入文字
pyautogui.typewrite('Hello from PyAutoGUI!', interval=0.05)
pyautogui.press('enter')
pyautogui.typewrite('This is automated typing.', interval=0.05)

# 儲存（Ctrl + S）
pyautogui.hotkey('ctrl', 's')
time.sleep(1)

# 在另存新檔視窗中輸入檔名
pyautogui.typewrite('auto_test.txt', interval=0.05)
pyautogui.press('enter')

print("完成！已儲存為 auto_test.txt")

練習題

📝 練習題 1：自動全選並複製

題目：在任意文字編輯器中，用 PyAutoGUI 執行「全選→複製→游標移至末尾→貼上」的操作序列。

答案：

import pyautogui
import time

time.sleep(2) # 手動切換到目標視窗

pyautogui.hotkey('ctrl', 'a') # 全選
time.sleep(0.3)
pyautogui.hotkey('ctrl', 'c') # 複製
time.sleep(0.3)
pyautogui.press('end') # 移至末尾
pyautogui.press('enter') # 換行
pyautogui.hotkey('ctrl', 'v') # 貼上

📝 練習題 2：詢問使用者再執行

題目：用 confirm() 彈出確認視窗，若使用者點「確定」，才執行自動輸入文字的動作；若點「取消」，則印出「已取消」。

答案：

import pyautogui
import time

result = pyautogui.confirm('是否要開始自動輸入？', title='確認', buttons=['確定', '取消'])

if result == '確定':
 time.sleep(2) # 切換到目標視窗
 pyautogui.typewrite('自動輸入的文字！', interval=0.1)
else:
 print('已取消')

📝 練習題 3：模擬 Vim 儲存並離開

題目：假設 Vim 已開啟並在 Normal mode，用 PyAutoGUI 模擬輸入 :wq 後按 Enter 來儲存並離開。

答案：

import pyautogui
import time

time.sleep(2) # 切換到 Vim 視窗

# 確保在 Normal mode
pyautogui.press('esc')
time.sleep(0.2)

# 輸入 :wq 指令
pyautogui.typewrite(':wq', interval=0.1)
pyautogui.press('enter')

參考資料

如何使用 PyAutoGUI（三）：螢幕截圖與圖像辨識

Sat, 02 May 2026 21:40:44 +0800

1. 截取螢幕畫面

全螢幕截圖 `screenshot()`：

在 1920 x 1080 的螢幕上，screenshot()大約需要 100 毫秒。

import pyautogui

# 截取全螢幕，回傳 PIL Image 物件
img = pyautogui.screenshot()

# 顯示圖片（需安裝 Pillow）
img.show()

# 直接儲存為檔案
pyautogui.screenshot('screenshot.png')

# 截圖並儲存
img = pyautogui.screenshot('my_screen.png')
print(f"截圖尺寸：{img.size}") # (寬, 高)

區域截圖 `screenshot(region=(...)))`：

region 參數格式為 (left, top, width, height)，分別表示要截圖區域的左側、頂部、寬度和高度。

import pyautogui

# 截取左上角 400x300 的區域
img = pyautogui.screenshot(region=(0, 0, 400, 300))

# 截取螢幕中央的 200x200 區域
screen_w, screen_h = pyautogui.size()
cx = screen_w // 2 - 100
cy = screen_h // 2 - 100
img = pyautogui.screenshot(region=(cx, cy, 200, 200))
img.save('center_crop.png')

💡 補充說明：PIL Image 物件
screenshot() 回傳的是 Pillow 的 Image 物件，可以進一步進行旋轉、裁切、濾鏡等影像處理，也可以轉成 NumPy 陣列配合 OpenCV 使用：
import numpy as np
import cv2

img = pyautogui.screenshot()
frame = np.array(img)
frame = cv2.cvtColor(frame, cv2.COLOR_RGB2BGR)
cv2.imwrite('screen_cv2.png', frame)

2. 圖像辨識：在螢幕上尋找圖片

PyAutoGUI 可以在當前螢幕畫面中搜尋指定圖片，回傳其位置。

前置條件：需先準備好要搜尋的圖片（.png 格式最佳），可用截圖工具截取目標按鈕或圖案。

⚠️ 注意：新舊版本差異
在新版 PyAutoGUI 中，若找不到圖片會拋出 pyautogui.ImageNotFoundException；如果是舊版，則會回傳 None，可以使用 if location: 來判斷。
建議統一使用 try...except 來確保程式不會崩潰。

尋找圖片位置 `locateOnScreen()`：

import pyautogui

try:
 # 在螢幕上尋找 button.png，找到則回傳 Box(left, top, width, height)
 location = pyautogui.locateOnScreen('button.png')
 print(f"找到圖片：{location}")
 # location.left, location.top, location.width, location.height
except pyautogui.ImageNotFoundException:
 print("找不到圖片")

取得圖片中心座標 `locateCenterOnScreen()`：

import pyautogui

try:
 # 找到圖片並直接回傳中心點座標 (x, y)
 center = pyautogui.locateCenterOnScreen('button.png')
 x, y = center
 print(f"圖片中心：({x}, {y})")
 pyautogui.click(x, y)
except pyautogui.ImageNotFoundException:
 print("找不到圖片")

調整信心值（confidence）

當截圖與螢幕畫面因縮放或顯示設定略有差異時，可調整 confidence 參數（需安裝 opencv-python）：

pip install opencv-python

import pyautogui

# confidence 介於 0~1，預設為 1.0（完全相符）
# 降低至 0.8 可接受 80% 的相似度
try:
 location = pyautogui.locateOnScreen('button.png', confidence=0.8)
 print(f"找到圖片：{location}")
except pyautogui.ImageNotFoundException:
 print("找不到圖片")

尋找所有符合位置 `locateAllOnScreen()`：

import pyautogui

try:
 # 回傳所有符合位置的 generator
 all_locations = list(pyautogui.locateAllOnScreen('icon.png'))
 print(f"共找到 {len(all_locations)} 個符合位置")
 for loc in all_locations:
 print(loc)
except pyautogui.ImageNotFoundException:
 print("找不到任何符合的圖片")

在圖片中搜尋 `locate()`（非螢幕）：

from PIL import Image
import pyautogui

# 在一張截圖檔案中搜尋另一張圖片
haystack = Image.open('fullscreen.png')
needle = Image.open('button.png')

try:
 location = pyautogui.locate(needle, haystack, confidence=0.9)
 print(location)
except pyautogui.ImageNotFoundException:
 print("在圖片中找不到目標圖案")

3. 像素顏色偵測

取得指定座標的像素顏色 `pixel()`：

import pyautogui

# 取得座標 (100, 200) 的 RGB 顏色值
r, g, b = pyautogui.pixel(100, 200)
print(f"顏色：RGB({r}, {g}, {b})")

判斷像素顏色是否符合 `pixelMatchesColor()`：

import pyautogui

# 判斷 (100, 200) 是否為紅色 (255, 0, 0)
is_red = pyautogui.pixelMatchesColor(100, 200, (255, 0, 0))
print(f"是紅色嗎？{is_red}")

# 允許一定的顏色誤差（tolerance 預設為 0）
is_approx_red = pyautogui.pixelMatchesColor(100, 200, (255, 0, 0), tolerance=30)
print(f"接近紅色嗎？{is_approx_red}")

實用應用：偵測載入完成

import pyautogui
import time

# 等待某個座標的顏色變成綠色（表示載入完成）
print("等待載入完成...")
while True:
 r, g, b = pyautogui.pixel(500, 300)
 if g > 200 and r < 100 and b < 100: # 接近綠色
 print("載入完成！")
 break
 time.sleep(0.5)

4. 實戰範例：自動點擊指定按鈕

以下範例示範如何找到螢幕上的「送出」按鈕圖片並自動點擊：

import pyautogui
import time

def click_button(image_path, confidence=0.9, timeout=10):
 """
 在螢幕上搜尋圖片並點擊，若超過 timeout 秒仍找不到則拋出例外。
 """
 start_time = time.time()

 while True:
 try:
 location = pyautogui.locateCenterOnScreen(image_path, confidence=confidence)
 if location:
 pyautogui.click(location)
 print(f"成功點擊：{image_path}")
 return True
 except pyautogui.ImageNotFoundException:
 pass

 if time.time() - start_time > timeout:
 raise TimeoutError(f"超過 {timeout} 秒仍找不到：{image_path}")

 time.sleep(0.5)

# 使用範例
try:
 click_button('submit_button.png', confidence=0.85, timeout=15)
except TimeoutError as e:
 print(f"錯誤：{e}")

5. 實戰範例：等待圖案出現再執行

import pyautogui
import time

def wait_for_image(image_path, confidence=0.85, check_interval=1.0):
 """
 持續等待直到螢幕出現指定圖片，回傳中心座標。
 """
 print(f"等待出現：{image_path}")

 while True:
 try:
 center = pyautogui.locateCenterOnScreen(image_path, confidence=confidence)
 if center:
 print(f"已找到，座標：{center}")
 return center
 except pyautogui.ImageNotFoundException:
 pass

 time.sleep(check_interval)


# 完整自動化流程範例
import pyautogui, time

time.sleep(3) # 等待目標程式啟動

# 等待「登入」按鈕出現
login_btn = wait_for_image('login_button.png')
pyautogui.click(login_btn)
time.sleep(0.5)

# 輸入帳號密碼
pyautogui.typewrite('user@example.com', interval=0.05)
pyautogui.press('tab')
pyautogui.typewrite('mypassword', interval=0.05)

# 等待「送出」按鈕出現並點擊
submit_btn = wait_for_image('submit_button.png')
pyautogui.click(submit_btn)

# 等待「歡迎」畫面出現，確認登入成功
wait_for_image('welcome_screen.png')
print("登入成功！")

6. 常見問題與除錯技巧

問題 1：`locateOnScreen()` 找不到圖片

可能原因與解決方式：

原因	解決方式
螢幕縮放不同（HiDPI / Retina）	降低 `confidence` 值，例如 `0.8`
圖片有些微色差	加入 `grayscale=True` 進行灰階比對
圖片不在當前可視範圍	確認視窗是否最小化或被遮擋
圖片解析度不符	重新截取在目標機器上的按鈕圖片

# 灰階比對，對顏色差異更有容忍度
location = pyautogui.locateOnScreen('button.png', grayscale=True, confidence=0.8)

問題 2：macOS 截圖需要授權

在 macOS 上，需至「系統設定 → 隱私權與安全性 → 螢幕錄製」，將執行 Python 的終端機加入允許清單。

問題 3：速度太快造成錯誤

import pyautogui

# 增加全域延遲
pyautogui.PAUSE = 0.3

# 或在關鍵步驟加入 time.sleep()
import time
time.sleep(0.5)

取得當前像素顏色的小工具

import pyautogui, time

print("移動滑鼠到目標位置，3 秒後擷取顏色")
time.sleep(3)
x, y = pyautogui.position()
r, g, b = pyautogui.pixel(x, y)
print(f"座標 ({x}, {y}) 的顏色：RGB({r}, {g}, {b})")

練習題

📝 練習題 1：截取並儲存指定區域

題目：截取螢幕右下角 300x200 的區域，儲存為 corner.png。

答案：

import pyautogui

w, h = pyautogui.size()
region = (w - 300, h - 200, 300, 200)
pyautogui.screenshot('corner.png', region=region)
print("已儲存右下角截圖：corner.png")

📝 練習題 2：確認按鈕存在才點擊

題目：嘗試在螢幕上尋找 ok_button.png，若找到則點擊，否則印出「找不到按鈕」。

答案：

import pyautogui

try:
 center = pyautogui.locateCenterOnScreen('ok_button.png', confidence=0.85)
 if center:
 pyautogui.click(center)
 print("已點擊 OK 按鈕")
except pyautogui.ImageNotFoundException:
 print("找不到按鈕")

📝 練習題 3：像素顏色監控

題目：每秒偵測座標 (960, 540) 的像素顏色，若 R 值超過 200 則印出警告訊息並停止，最多監控 30 秒。

答案：

import pyautogui
import time

print("開始監控像素顏色...")
for i in range(30):
 r, g, b = pyautogui.pixel(960, 540)
 print(f"第 {i+1} 秒：RGB({r}, {g}, {b})")
 if r > 200:
 print("⚠️ 警告：R 值超過 200！")
 break
 time.sleep(1)
else:
 print("監控結束，未觸發警告")

Automation on YuChen

如何使用 PyAutoGUI（一）：安裝與滑鼠控制

內容大綱

1. PyAutoGUI 基本介紹

2. 安裝 PyAutoGUI

3. 螢幕座標系統

4. 安全機制：Fail-Safe

5. 取得螢幕資訊

6. 滑鼠點擊

點擊 click()：

雙擊 doubleClick()：

右鍵點擊 rightClick()：

中鍵點擊 middleClick()：

分開按下與放開 mouseDown() / mouseUp()：

7. 滑鼠移動

移動到絕對座標 moveTo(x, y, duration=num_seconds)：

移動到相對座標 moveRel(xOffset, yOffset, duration=num_seconds)：

拖曳到絕對座標 dragTo(x, y, duration=num_seconds)：

拖曳到相對座標 dragRel(xOffset, yOffset, duration=num_seconds)：

8. 滾輪操作

垂直滾動 scroll()

水平滾動 hscroll()

練習題

參考資料

如何使用 PyAutoGUI（二）：鍵盤控制

內容大綱

1. 文字輸入

typewrite() / write()

2. 單鍵操作：

按下並放開單一按鍵 press()：

按住不放與放開按鍵 keyDown() / keyUp()：

上下文管理器 hold()：

組合鍵與熱鍵 hotkey()：

3. 常用 Key 名稱對照表

4. 訊息彈出視窗

顯示訊息 alert()：

確認視窗 confirm()：

文字輸入視窗 prompt()：

密碼輸入視窗 password()（遮蔽顯示）：

5. 實用範例：自動開啟記事本並輸入文字

練習題

參考資料

如何使用 PyAutoGUI（三）：螢幕截圖與圖像辨識

內容大綱

1. 截取螢幕畫面

全螢幕截圖 screenshot()：

區域截圖 screenshot(region=(...)))：

2. 圖像辨識：在螢幕上尋找圖片

尋找圖片位置 locateOnScreen()：

取得圖片中心座標 locateCenterOnScreen()：

調整信心值（confidence）

尋找所有符合位置 locateAllOnScreen()：

在圖片中搜尋 locate()（非螢幕）：

3. 像素顏色偵測

取得指定座標的像素顏色 pixel()：

判斷像素顏色是否符合 pixelMatchesColor()：

4. 實戰範例：自動點擊指定按鈕

5. 實戰範例：等待圖案出現再執行

6. 常見問題與除錯技巧

問題 1：locateOnScreen() 找不到圖片

問題 2：macOS 截圖需要授權

問題 3：速度太快造成錯誤

取得當前像素顏色的小工具

練習題

參考資料

點擊 `click()`：

雙擊 `doubleClick()`：

右鍵點擊 `rightClick()`：

中鍵點擊 `middleClick()`：

分開按下與放開 `mouseDown()` / `mouseUp()`：

移動到絕對座標 `moveTo(x, y, duration=num_seconds)`：

移動到相對座標 `moveRel(xOffset, yOffset, duration=num_seconds)`：

拖曳到絕對座標 `dragTo(x, y, duration=num_seconds)`：

拖曳到相對座標 `dragRel(xOffset, yOffset, duration=num_seconds)`：

垂直滾動 `scroll()`

水平滾動 `hscroll()`

`typewrite()` / `write()`

按下並放開單一按鍵 `press()`：

按住不放與放開按鍵 `keyDown()` / `keyUp()`：

上下文管理器 `hold()`：

組合鍵與熱鍵 `hotkey()`：

顯示訊息 `alert()`：

確認視窗 `confirm()`：

文字輸入視窗 `prompt()`：

密碼輸入視窗 `password()`（遮蔽顯示）：

全螢幕截圖 `screenshot()`：

區域截圖 `screenshot(region=(...)))`：

尋找圖片位置 `locateOnScreen()`：

取得圖片中心座標 `locateCenterOnScreen()`：

尋找所有符合位置 `locateAllOnScreen()`：

在圖片中搜尋 `locate()`（非螢幕）：

取得指定座標的像素顏色 `pixel()`：

判斷像素顏色是否符合 `pixelMatchesColor()`：

問題 1：`locateOnScreen()` 找不到圖片