Playwright 引擎升級說明書

Mbbrowser Playwright 引擎自動化升級詳細說明書

第一版 Mbbrowser Playwright 引擎自動化解決方案現已正式發布。 作為目前全球領先的瀏覽器自動化測試框架，Playwright 憑藉其卓越的穩定性、強大的功能集以及對多種編程語言的原生支持，正逐漸成為開發者和測試工程師的首選。Mbbrowser 深度集成了 Playwright 核心，為用戶提供更為流暢、高效的群控與自動化體驗。

一、 為什麼選擇 Playwright？

在自動化領域，Selenium 與 Puppeteer 長期以來佔據著主導地位。然而，Playwright 作為微軟推出的新一代自動化工具，在多個維度上展現出了顯著優勢：

1. 原生多語言支持：提供對 JavaScript/TypeScript、Python、Java 和 .NET 的完美支持。
2. 彈性自動等待機制：Playwright 會自動等待元素變為可操作狀態（如可見、已加載），極大減少了腳本中顯式等待代碼的編寫，提升了腳本的穩健性。
3. 高性能內核交互：直接通過 Chrome DevTools Protocol (CDP) 的高級抽象進行通訊，相比 Selenium 的 HTTP 請求轉發機制，響應速度更決。
4. 強大的頁面上下文 (Isolation)：支持在單個瀏覽器執行實例中創建多個相互隔離的頁面上下文，非常適合併發業務處理。
5. 支持現代 Web 特性：原生支持 Shadow DOM、多窗口切換、地理位置偽裝、網絡抓包與攔截等高級功能。

二、 Mbbrowser Playwright 核心技術架構

Mbbrowser 對於 Playwright 的支持採用了「客戶端 API + CDP 轉發」的架構模式。

技術組件關係圖：

1. Mbbrowser Client (控制台)：負責環境配置管理、API 服務分發。
2. mbservice.exe (API 服務)：監聽 55555 端口，處理環境啟動請求。
3. cdp.exe (協議中轉)：當環境啟動後，cdp.exe 會監聽一個隨機或指定端口，作為 Playwright 連接的掛載點。
4. 候鳥瀏覽器 (內核)：基於 Chromium 的指紋瀏覽器實例，執行具體的指令操作。

三、 環境準備工作

在開始使用 Playwright 自動化之前，請確保您的開發環境已完成以下配置：

1. Mbbrowser 客戶端配置

• 下載並安裝最新版本的 Mbbrowser 客戶端（需支持 Playwright 內核版本）。
• 在「設置」中確保 API 服務已開啟（默認端口 55555）。

2. 開發語言環境 (以 Python 為例)

• 安裝 Python 3.8+。
• 安裝 Playwright 庫：pip install playwright。
• 注意：不需要執行 playwright install 來下載瀏覽器，因為我們將連接到 Mbbrowser 已有的內核。

四、 如何連接 Mbbrowser 與 Playwright

連接的核心是通過 Mbbrowser 的啟動 API 獲取 wsEndpoint (WebSocket 端點) 或 browserURL。

本地連接 (Python 示例)：

import time
import requests
from playwright.sync_api import sync_playwright

# 1. 通過候鳥 API 啟動環境並獲取 CDP 地址
def get_cdp_address(browser_id):
    url = f"http://127.0.0.1:55555/api/v1/browser/start?id={browser_id}"
    res = requests.get(url).json()
    if res['code'] == 0:
        return res['data']['address'] # 返回格式如 127.0.0.1:端口
    else:
        print("啟動環境失敗:", res['msg'])
        return None

def run_playwright():
    browser_id = "your_env_id"
    address = get_cdp_address(browser_id)
    
    if not address:
        return

    with sync_playwright() as p:
        # 2. 通過 connect_over_cdp 連接到候鳥瀏覽器
        # 注意：地址需要加上 http:// 前綴
        browser = p.chromium.connect_over_cdp(f"http://{address}")
        
        # 3. 獲取當前已打開的默認上下文和頁面
        context = browser.contexts[0]
        page = context.pages[0]
        
        # 4. 執行業務邏輯
        page.goto("https://www.mbbrowser.com")
        print("當前頁面標題:", page.title())
        
        # 模擬登錄操作 (示例元素選取)
        # page.fill("#username", "myuser")
        # page.click("button >> text=Login")
        
        time.sleep(5)
        print("自動化操作完成")

if __name__ == "__main__":
    run_playwright()

遠程併發控制 (Node.js 示例)：

const { chromium } = require('playwright');
const axios = require('axios');

(async () => {
    // 啟動 API 調用
    const envId = "your_env_id";
    const res = await axios.get(`http://127.0.0.1:55555/api/v1/browser/start?id=${envId}`);
    
    if (res.data.code === 0) {
        const address = res.data.data.address;
        
        // 連接瀏覽器
        const browser = await chromium.connectOverCDP(`http://${address}`);
        const defaultContext = browser.contexts()[0];
        const page = defaultContext.pages()[0];

        await page.goto('https://whoer.net');
        console.log('瀏覽器指紋檢測中...');
        
        // 拍照截圖
        await page.screenshot({ path: 'fingerprint.png' });
        
        // 釋放連接 (不關閉瀏覽器)
        await browser.close(); 
    }
})();

五、 Mbbrowser Playwright 專屬優化功能

為了讓 Playwright 在指紋瀏覽器環境中表現更出色，我們在核心層面進行了以下優化：

1. 自動匹配指紋上下文：當 Playwright 連接後，它會自動繼承 Mbbrowser 在環境配置中設置的所有指紋屬性（UA、Canvas、WebGL、WebRTC 等）。
2. 網絡請求攔截與偽裝：支持 Playwright 的 route 方法，可以自定義修改請求頭或 Mock 響應數據，這在複雜的爬蟲業務中非常有用。
3. 多窗口穩定性增強：解決了在大量併發群控時，傳統 Selenium 容易出現的窗口丟失或句柄死鎖問題。
4. Cookie 與 Session 持久化：自動處理環境級別的 Cookie 存儲，確保自動化操作前後的登錄狀態一致。

六、 從 Selenium/Puppeteer 遷移到 Playwright 的建議

1. 語法轉換：Playwright 的 API 設計更加符合直覺。例如 Selenium 的 find_element 在 Playwright 中簡化為 page.locator 或直接在動作方法中傳入 selector。
2. 利用 Codegen：Playwright 提供了強大的代碼生成工具。您可以運行 playwright codegen 來錄製您的手動操作並自動生成代碼。
3. 異常處理：建議使用 try...except 包裹 API 調用部分，因為網絡波動可能導致 CDP 連接暫時不穩定。
4. 資源釋放：完成腳本後調用 browser.close() 僅會斷開自動化控制鏈接，環境本身是否保持運行取決於您的 API 調用參數設置。

七、 常見問題解答 (FAQ)

Q: 為什麼連接時提示 Connection Refused？ A: 請檢查：1. Mbbrowser 的 API 服務是否已開啟；2. 目標環境是否已成功啟動（可以在客戶端界面查看狀態）；3. 防火牆是否禁用了對應的 CDP 端口。

Q: Playwright 支持在候鳥中更換代理嗎？ A: 支持。雖然您可以在環境配置中預設代理，但 Playwright 也允許在代碼中通過代理中轉實現動態更換。

Q: 我需要像常規 Playwright 安裝那樣運行 npm install playwright 嗎？ A: 是的，您需要安裝庫文件以獲得 API 代碼補全 and 運行環境支持，但無需下載對應的瀏覽器二進位制文件。

---

Mbbrowser 將持續完善 Playwright 引擎的兼容性與功能深度。如果您在開發過程中遇到任何問題，歡迎通過官方社群或技術支持渠道向我們反饋。