Claude Code 如何透過 Playwright 操作瀏覽器

遊戲頁面已經寫好，也能在瀏覽器中正常開啟：棋盤會顯示，棋子能移動，"新棋局"按鈕也在該在的位置。不過代理本身從未看過這個頁面。它只處理過檔案文字；是您啟動瀏覽器、查看頁面，再把結果告訴它。Playwright 正好補上這個落差：代理開啟同一個頁面，找到需要的元素，點擊它，再讀取之後的變化。

以下以西洋棋頁面為例，逐步走過這個流程：開啟、查看、選取元素、操作、讀取新狀態。這裡不重講安裝和連接伺服器的方式；如果您還沒設定 Playwright，請參考專案的 README。

開啟需要的頁面

Connected 這個標示能證明什麼？
只有一件事：Claude Code 已連上 Playwright 伺服器，並取得工具清單。此時還沒開啟任何頁面，瀏覽器甚至可能尚未啟動。Connected 說的是連線，不代表遊戲已正常運作，也不代表代理看得到遊戲。

您可以用 /mcp 指令查看目前狀態：它會列出已連接的伺服器，以及各自提供的功能。真正的工作從這裡才開始，而第一步需要頁面網址。

本機遊戲可能是磁碟上的檔案，也可能跑在本機伺服器上；伺服器的連接埠不會永遠相同。5173、8000、3000，要看您用什麼方式啟動。請從實際顯示網址的地方複製：啟動指令的輸出，或剛才查看遊戲的瀏覽器網址列。猜錯連接埠，看到的可能是空白頁面，甚至是別的專案；工具的回覆也不一定能讓您立刻察覺。

開啟頁面是獨立的呼叫 browser_navigate，只有一個參數：url。交給代理的指示可以用一般語言描述：

請透過 Playwright 開啟 http://localhost:5173/
並顯示開啟頁面的標題。

開啟後請核對兩件事：代理實際前往的網址，以及頁面名稱。只花一秒，卻能省下在錯誤頁面上連續操作的時間。尤其是您同時跑著好幾個本機專案，而其中一個也在 localhost 回應時。

代理能看到頁面上的什麼

查看已開啟的頁面有三種方式，得到的資訊也完全不同：

三種方式都從同一個頁面開始，回傳的資料卻不一樣。快照能協助尋找按鈕，而 data-turn 的值必須另外讀取。只看棋盤圖片，無法得知它的 HTML 屬性。

截圖就是一張圖片，很適合回答"看起來如何"、"東西在哪裡"這類問題，但它不會提供 browser_click 所需的元素參照。在 Playwright MCP 的主要模式中，操作會使用無障礙快照。如果啟用了對應工具，也能另外用座標點擊。

無障礙快照就是元素描述。它不是圖片，而是文字：列出頁面由哪些元素組成、各自的角色（按鈕、連結、輸入欄位）、名稱和之後可用來定位元素的參照。代理點擊時，依據的正是這些資訊。快照中的按鈕大致會像這樣：

- button "新棋局" [ref=e12]
- button "復原棋步" [ref=e13]

這是用來理解格式的示意，不是工具的實際輸出：確切格式會依伺服器版本而異，我們不會為了文章特地執行工具。重點不在標點，而是按鈕會以一行文字交給代理，裡面有角色、名稱和參照，而不是一個帶文字的矩形。

最容易混淆的地方來了。我們的遊戲用 data-turn 標記目前輪到誰，但這個標記不會出現在無障礙快照中：快照根據角色、名稱、狀態和元素參照建立，而不是根據頁面的 HTML。任意的 data 屬性不在其中。不過，如果頁面也把標記值顯示成可見文字，它可能會另外出現在快照裡；但那是頁面上的文字，不是讀取到的屬性，兩者不要混為一談。

這類值要透過另一項操作，也就是 browser_evaluate 工具來讀取。它會在頁面的情境中執行簡短運算式並回傳結果；這已經是在頁面上執行程式碼，而不只是讀取，因此代理有時會先詢問是否允許。運算式由代理自行撰寫，大致如下：

// 找出標記目前棋步的元素，並回傳它的值
() => document.querySelector('[data-turn]')?.getAttribute('data-turn') ?? null

代理如何選取元素

為什麼用座標點擊，有時會點不到按鈕？
因為座標描述的是螢幕上的一個點，不是按鈕。您調整視窗大小、收起側邊欄、改變字體縮放，或頁面頂端多出一行內容，點的位置沒變，按鈕卻移開了。點擊還是會執行，只是落在空白處。

所以主要的選取方式不一樣。browser_click 工具有兩個重要欄位：element 是容易理解的描述，例如"新棋局按鈕"，讓您知道代理準備點哪裡；target 則是快照中的元素參照或唯一選擇器。這裡討論的是用快照參照選取。參照和產生它的快照綁定，點擊會落在那個元素上。輸入文字的方式也類似，只是工具名稱是 browser_type，而且會在元素描述之外附上要輸入的文字。

真正穩定的不是參照本身，而是尋找元素的方法。角色加名稱是一組相當固定的線索：設計師把按鈕移到螢幕另一邊後，"新棋局"按鈕仍然叫"新棋局"。代理可在每份新快照中依這組線索重新找到元素，取得最新參照。這也是文章後面不斷提醒"每次操作後都重新查看"的原因。

棋盤格就比較麻煩：總共有 64 格，而且角色都一樣。這時可以使用應用程式提供的標記。如果棋格有自己的名稱，例如 e2 或 e4，就能精確選取；如果快照裡的棋格都沒有名稱，只靠角色和名稱就無法選到特定一格。這時要檢查頁面 HTML 中是否有其他明確特徵，或使用可用的座標工具。

Playwright MCP 也提供座標工具，但標準組態預設會關閉，需要另外啟用，以便處理 canvas 等無法用其他方式觸及的元素。既然標準組態沒有這些工具，只靠一張圖片確實無法操作，這正是本節開頭提醒截圖限制的原因。

操作與新狀態

左側的箭頭讓流程回到起點：代理在下一次操作前，會使用頁面的最新描述。如果前一次操作的回覆已包含新快照，就能直接依據它。點擊成功本身還不能證明預期的變化已經發生。

把所有步驟串成一條可以整個交給代理的流程吧。總共五步，每一步都能確認接下來應該看到什麼。這套流程假設棋盤格都有名稱，也就是前一節提到的 e2 和 e4；如果沒有名稱，第 4 步就需要另一種能明確選取棋格的方式。

左側是原本的狀態，右側是預期的棋步結果。下方的區塊把兩者連起來：代理重新讀取輪到誰的標記和棋子位置，再比較這些值。若要更完整地確認移動，也要檢查原本的 e2 是否已空出。只看到 white 變成 black，還不能證明白兵確實移到了 e4。

關於 data-turn，要說清楚一點：這是特定應用程式自行約定的標記。頁面作者決定提供這個標記，所以我們才能讀取它。Playwright 不會建立或推測這個值，只能讀取頁面上已經存在的內容。其他頁面如果沒有設定這個標記，這個方法就行不通，只能依靠頁面上看得到的資訊。

每次操作後最重要的規則是：重新讀取狀態。點擊前建立的快照描述的是點擊前的頁面，不管看起來有多新。棋盤重新繪製後，快照中的元素參照可能已經失效；點擊前另外讀到的 data-turn 也可能改變了。操作完成後，就再查看一次。

操作沒有成功時

最常見的狀況是"找不到元素"。可以依序簡單檢查：

1. 確認開啟的是正確頁面。網址和標題，還是最開始提到的那兩項；
2. 確認頁面已載入完成。遊戲可能還在載入，按鈕也可能比請求晚一秒才出現；
3. 重新取得快照。不要沿用對話裡已經存在的快照，請建立一份新的；
4. 依照新快照中的最新描述重新選取元素，再試一次。

其中一種可能的原因會在第三步浮現：元素仍在頁面上，但它的參照已經過期。

排查時截圖也有幫助，但不是萬用工具。它能回答"頁面看起來如何、各項內容在哪裡"，例如棋盤是否空白，或上面是否出現對話視窗。如果輪到誰以文字顯示在頁面上，截圖也看得到。但只有讀取 data-turn 屬性，才能確認它的確切值。這是兩個不同的問題，要用不同工具；把它們混為一談，就像看著圖片卻爭論資料。

這會如何改變工作方式

交給代理的指示不再只是點擊清單，而是一條有檢查點的流程。把剛才的內容整理成一段指示如下：

請透過 Playwright 開啟 http://localhost:5173/。
1) 點擊"新棋局"；
2) 讀取 data-turn 並顯示它的值；
3) 透過頁面介面走 e2-e4；
4) 再次讀取 data-turn 和 e4 上的棋子。
如果頁面上沒有其中某個值，請明確說明，
不要自行推測。

請記住幾個重點：

• 使用實際網址，也就是從啟動輸出取得的網址，不要猜；
• 指示中要明確要求"讀取並顯示"，否則您只會看到結果摘要；
• 操作前後的狀態要成對顯示。只看到最後一個值無法證明什麼，因為不知道操作前是什麼狀態；
• 快照、截圖和讀取屬性分別回答不同問題，應依問題選擇，不要只憑習慣；
• 一條示範流程就夠了。成功走完 e2-e4，不代表之後整盤棋都會符合規則；那是另一項複雜得多的檢查。

最簡單的記法是：瀏覽器給了代理雙手和眼睛，卻不會直接給它結論。它可以自行開啟頁面、點擊和讀取值；至於這個值代表什麼，仍然由您判斷。

工具名稱和參數已於 2026 年 9 月 19 日對照 Playwright MCP README 核實，並可能隨版本變動。整體流程仍然是：開啟、查看、選取元素、操作、重新讀取。