快速開始：接管候鳥環境
本章節提供一個可直接複製運行的 Python 腳本，帶領您從零開始成功接管候鳥指紋環境，並完成第一個自動化任務。
完整腳本 (複製即可使用)
創建一個名為 start_selenium.py 的文件，粘貼以下代碼並修改配置部分：
python
import requests
import time
from selenium import webdriver
from selenium.webdriver.chrome.options import Options
from selenium.webdriver.chrome.service import Service
# ============================
# 配置部分：請修改為您自己的信息
# ============================
API_URL = "http://127.0.0.1:8186"
SESSION_ID = "replace_with_your_session_id" # 在候鳥中右鍵 -> 複製環境 ID 獲取
# 候鳥目錄下 chromedriver.exe 的路徑 (或者設為 None 讓 Selenium Manager 自動匹配)
DRIVER_PATH = r"C:\Program Files (x86)\Mbbrowser_v7.10.20.219\chromedriver.exe"
def start_browser():
"""
第一步：告訴候鳥 ApiServer 開啟指定環境
第二步：從返回值中獲取 debuggerAddress
第三步：使用 Selenium 接管該環境
第四步：執行業務邏輯
"""
# ── 步驟 1: 開啟候鳥環境 ──────────────────────────
print("⏳ 正在啟動候鳥指紋環境...")
try:
response = requests.post(
f"{API_URL}/api/v1/browser/start",
json={"Session_ID": SESSION_ID},
timeout=30
)
data = response.json()
except requests.exceptions.ConnectionError:
print("❌ 無法連接 ApiServer。請確保它已啟動且端口正確！")
return
if data.get("code") != 0:
print(f"❌ 環境啟動失敗: {data.get('message')}")
return
# ── 步驟 2: 提取遠程調試地址 ──────────────────────
# data["data"]["http"] 的格式為: 127.0.0.1:9222
debugger_address = data["data"]["http"]
print(f"✅ 環境已開啟。遠程調試地址: {debugger_address}")
# ── 步驟 3: 配置 Selenium 進行接管 ───────────────────
chrome_options = Options()
# 這是接管已有瀏覽器（而不是新建一個）的關鍵參數！
chrome_options.add_experimental_option("debuggerAddress", debugger_address)
# 如果您有候鳥自帶的 chromedriver，請指定路徑；
# 否則設為 None 讓 Selenium Manager 自動處理。
if DRIVER_PATH:
service = Service(executable_path=DRIVER_PATH)
driver = webdriver.Chrome(service=service, options=chrome_options)
else:
driver = webdriver.Chrome(options=chrome_options)
print("🎉 Selenium 接管成功！")
# ── 步驟 4: 執行您的業務邏輯 ─────────────────────────
try:
# 跳轉到目標網址
driver.get("https://www.mbbrowser.com")
print(f"📄 當前網頁標題: {driver.title}")
# 等載 3 秒觀看效果
time.sleep(3)
print("✅ 腳本執行完畢！")
finally:
# 注意：這只是「斷開 Selenium 連接」
# 候鳥環境視窗會繼續運行
# 如需徹底關閉瀏覽器，請調用 /api/v1/browser/stop 接口
driver.quit()
if __name__ == "__main__":
start_browser()運行腳本:
bash
python start_selenium.py預期輸出
⏳ 正在啟動候鳥指紋環境...
✅ 環境已開啟。遠程調試地址: 127.0.0.1:9222
🎉 Selenium 接管成功！
📄 當前網頁標題: 候鳥防關聯瀏覽器-多帳號解決方案
✅ 腳本執行完畢！逐行解析
1. 調用 ApiServer 啟動環境
python
response = requests.post(
f"{API_URL}/api/v1/browser/start",
json={"Session_ID": SESSION_ID}
)- 此步驟告訴候鳥：「請幫我打開 Session_ID 為
XXX的指紋環境」。 - ApiServer 收到請求後，會啟動對應的 Chrome 實例，並開啟遠程調試端口。
2. 提取 debuggerAddress
python
debugger_address = data["data"]["http"] # 例如 127.0.0.1:9222http字段中的信息是 Chrome 的遠程調試端口地址 (通常是127.0.0.1:端口)。- 每個候鳥環境都有一個唯一的端口號，由候鳥自動分配，互不衝突，可同時多開。
3. 設置 debuggerAddress 進行接管 (核心步驟!)
python
chrome_options.add_experimental_option("debuggerAddress", debugger_address)
driver = webdriver.Chrome(options=chrome_options)這是候鳥 Selenium 自動化與普通 Selenium 的本質區別：
| 動作 | 普通 Selenium | 候鳥 Selenium |
|---|---|---|
| 創建 Driver | 啟動一個全新的、空白的 Chrome 窗口 | 連接並接管一個已經存在的候鳥瀏覽器 |
| 指紋特徵 | 無，裸奔狀態 | 全套指紋 (UA, Canvas, WebGL, IP 等全部就緒) |
| Cookie 狀態 | 空，需重新登錄 | 繼承之前的登錄狀態 (若之前已登錄) |
4. 運行結束處理
python
driver.quit() # 斷開 Selenium 控制 (候鳥環境保持運行)NOTE
driver.quit() 僅斷開 Selenium 對瀏覽器的控制路徑，並不會關閉候鳥窗口。
如需徹底關閉瀏覽器，請調用：
python
requests.post(f"{API_URL}/api/v1/browser/stop", json={"Session_ID": SESSION_ID})常見問題故障排除
❓ 報錯: Cannot connect to the Service
原因: chromedriver.exe 版本與候鳥內核不匹配。 解決: 1. 使用候鳥目錄下的 chromedriver.exe 並在 Service 中指定路徑。2. 或者刪除 DRIVER_PATH 配置 (設為 None)，讓 Selenium Manager 處理。
❓ 報錯: ConnectionError: Cannot connect to ApiServer
原因: ApiServer 未啟動，或者端口填寫錯誤。 解決: 1. 確認 ApiServer 終端窗口還在運行。2. 確認 API_URL 中的端口與 --port 參數一致。3. 檢查防火牆是否攔截 8186 端口。
❓ 報錯: code != 0: 環境啟動失敗
原因: Session_ID 錯誤，或者環境已經在運行中。 解決: 1. 確認在候鳥中複製的是正確的 Session_ID。2. 如果環境已在運行，請先調用 stop 接口關閉後再啟動。
❓ 瀏覽器打開了，但不是登錄後的狀態
原因: 這是第一次開啟該環境，您還沒有手動登錄過，所以 Cookie 是空的。 解決: 這是正常現象。下一步請閱讀 核心 API 參考 學習如何注入 Cookie 或自動化登錄。
TIP
腳本跑通了？下一章 核心 API 參考 將教您如何用 Selenium 進行更複雜的操作：元素定位、輸入、點擊、等待、截圖...全部都有！