GoでchromedpにCAPTCHAソルバーを追加する方法

TL;DR

• chromedp は Go から Chrome を操作するライブラリであり、許可されたワークフローで CAPTCHA が必要になったときだけ、別サービスが解答結果を供給する。
• chromedp のバージョンを固定すること。現在のサンプルは古いチュートリアルと異なる API を使っている。
• 有料チャレンジを走らせる前に、「ブラウザアクセス」と「ソルバー API 接続」をそれぞれ個別にテストする。
• Go のエラーと API の ErrorId の両方を検査すること。Go のエラーが nil でもサービス成功とは限らない。
• ブラウザ上の現在のチャレンジ入力は必ずまとめて保持し、結果を適用したあとにページを検証する。

chromedp は Chrome DevTools Protocol 経由でブラウザを制御する Go 向けライブラリである。開発者は Python や JavaScript のコントローラを追加せずにブラウザテストや自動化ができる。許可されたブラウザタスクが対応する CAPTCHA に遭遇したとき、Go アプリケーションはソルバーを呼び出し、同じページの操作を継続できる。

CapSolver は公式の Go SDK とタスク API ドキュメントを提供しており、解答処理を担当する。このガイドは、ブラウザライブラリをソルバーそのものとして扱うのではなく、その役割同士を接続する方法を説明する。実行可能なチェックでは、自前のローカルブラウザフィクスチャと、明示的に無効なプレースホルダーキーを使った実際の API リクエストを使用する。これは配線とエラーハンドリングを検証するものであり、有料の解答を行うものではない。

chromedp における CAPTCHA 解答の位置付け

CAPTCHA 解答は、「現在のチャレンジパラメータ収集」と「解答結果を必要とするブラウザ操作の継続」の間に位置付けられる。

公式の chromedp リポジトリがブラウザコントローラを提供する。Go プログラムは許可されたページを開き、関連する状態を読み取り、対応するチャレンジを処理すべきか判断する。ソルバーはドキュメント化された出力を返し、chromedp はその後のページ操作を担当し続ける。

CAPTCHA があるからといって、停止したすべてのブラウザ操作が解答リクエストを必要とするとは限らない。入力漏れ、ナビゲーション失敗、アプリケーションエラーなど、別の修正を要する場合もある。タスクタイプを選ぶ前に、実際のチャレンジ内容を特定すること。

自前の QA フォームであれば、シーケンスは単純だ。フォームを開き、その CAPTCHA 設定を特定し、適切なタイミングで解答を要求し、アプリケーションが想定する統合経路で結果を適用し、フォームの確認結果をチェックする。このガイドは任意サイト向けの汎用コールバックや送信スクリプトを提供するものではない。

互換性のある Go 依存関係をインストールする

この記事の API 呼び出しがビルドと一致するよう、分離した Go モジュールとバージョン固定された依存関係を使用する。

検証済みの環境では、Go 1.27.3、github.com/chromedp/chromedp@v0.21.0、github.com/capsolver/capsolver-go@v0.0.0-20251204081438-e4e07af23eae を使用した。Chrome はローカルにインストールされ、別個の一時ブラウザコンテキストで起動されている。

作業ディレクトリを作成し、go mod init captcha-browser-check でモジュールを初期化したうえで次を実行する。

go get github.com/chromedp/chromedp@v0.21.0 github.com/capsolver/capsolver-go@v0.0.0-20251204081438-e4e07af23eae

v0.21.0 のリリースノートによれば、Go 1.25 以降がサポートされている。古いブラウザスクリプトを移行する際は、そのバージョンのドキュメントを参照すること。古いポインタ出力のサンプルと新しい型付きアクション API を混在させると、ブラウザやソルバーへのリクエストが実行される前にコンパイルエラーが発生しうる。

公式の残高 API ドキュメントには Go SDK の Balance() メソッドが含まれている。残高呼び出しは、アカウント／API アクセス確認とチャレンジ固有の解答処理を分離するのに役立つ。これ自体は CAPTCHA タスクを作成しない。

ブラウザと API 接続チェックを実行する

Chrome が自前ページを読み取れることと、Go SDK が実際の API レスポンスを受信できることを証明する小さなチェックを実行する。

以下を main.go として保存し、初期化済みモジュールで go run . を実行する。ローカルの FIXTURE_ONLY 属性はテストデータであり、実際の sitekey ではない。API キーは意図的に無効であり、プログラムはサービスがこれを拒否することを期待している。

package main

import (
    "context"
    "fmt"
    "log"
    "net/http"
    "net/http/httptest"
    "time"
    "github.com/chromedp/chromedp"
    capsolver "github.com/capsolver/capsolver-go"
)

func main() {
    // ローカルフィクスチャでブラウザ配線をチェックする。実際の CAPTCHA ではない。
    fixture := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        fmt.Fprint(w, `<title>Owned QA fixture</title><div id="widget" data-sitekey="FIXTURE_ONLY"></div>`)
    }))
    defer fixture.Close()
    ctx, cancel := chromedp.NewContext(context.Background())
    defer cancel()
    ctx, deadline := context.WithTimeout(ctx, 30*time.Second)
    defer deadline()
    if err := chromedp.Do(ctx, chromedp.Navigate(fixture.URL)); err != nil { log.Fatal(err) }
    sitekey, err := chromedp.Run(ctx, chromedp.AttributeValue("#widget", "data-sitekey"))
    if err != nil { log.Fatal(err) }
    if !sitekey.Exists || sitekey.Value != "FIXTURE_ONLY" { log.Fatal("Fixture key not found") }; fmt.Println("Fixture key:", sitekey.Value)
    // わざと無効な認証情報: アカウントではなく実際の API エラーを確認する。
    solver := capsolver.CapSolver{ApiKey: "YOUR_API_KEY"}
    result, err := solver.Balance()
    if err != nil { log.Fatal(err) }
    fmt.Println("API error:", result.ErrorId, result.ErrorCode)
    if result.ErrorId == 0 { log.Fatal("Expected the placeholder credential to be rejected") }
}

検証済みの実行では、Fixture key: FIXTURE_ONLY に続いて ErrorId が 1、ERROR_KEY_DOES_NOT_EXIST の API エラーが出力された。この正確なコードは、このプレースホルダーチェックに対して観測されたレスポンスとして扱い、すべての無効な認証情報に対する保証されたレスポンスとみなしてはならない。

これにより、ローカルブラウザへのアクセスと API への実際のリクエスト／レスポンス経路が確立される。実際のアカウントは照会されず、チャレンジは解答されず、フォーム送信も行われていない。

返却された属性を明示的に検査する

現在の AttributeValue アクションは、属性値と存在フラグを含む AttributeResult を返す。

サンプルでは、先に進む前に両フィールドをチェックしている。欠落した属性は、有料リクエストの空 sitekey になるのではなく、パラメータ収集を停止すべきだ。この自前フィクスチャで機能するセレクタは、すべての CAPTCHA 連携に通用する汎用セレクタではない。

ビジネスエラーと Go エラーを分けて確認する

検証済み SDK は、Go エラーを返さずに解析済みサービスレスポンスを返すことがある。

そのためサンプルは err を処理したあとに result.ErrorId をチェックしている。ネットワーク障害、JSON パース失敗、アカウントエラーを記述した正常なレスポンスは、それぞれ別の状況だ。アカウントやタスクが成功したと決めつけるのではなく、返却されたレスポンスを正確に読むこと。

CapSolver ボーナスコードを利用しよう

自動化予算を即座にブースト！
チャージ時にボーナスコード CAP26 を使用すると、すべてのリチャージで無制限に 5% ボーナス が付与されます。
今すぐ CapSolver ダッシュボード で引き換えましょう。

現在のチャレンジをドキュメント化されたタスクにマッピングする

実際に確認したページの情報から、選択した CAPTCHA の現在のタスクリファレンスを使って解答リクエストを組み立てる。

reCAPTCHA v2 の場合、公式タスクドキュメントにタスクファミリーや websiteURL、websiteKey などのフィールドが定義されている。ドキュメントに記載された綴りと大文字／小文字を使用すること。タスク名を記憶だけで作ったり、最新の契約内容を確認せずに古い SDK サンプルをコピーしたりしてはならない。

公式 Go SDK はタスクマップ用に Solve() を公開している。本番実装では、本物の認証情報を安全に供給し、最新のタスクパラメータを渡し、固定した SDK バージョンに従って返却結果またはエラーを検査する必要がある。

上記の接続チェックは、意図的に「完全な有料解答プログラム」ではない。解答ステップをデプロイする前に、自前で所有し許可されたアプリケーションに対して、資金を入れた自分のアカウントを使い、1 件のチャレンジを実行して結果を検証すること。この認証情報依存ステップは本記事では実行していないため、成功率やエンドツーエンド完了については一切保証しない。

ページ URL、チャレンジファミリー、公開鍵、および必要なオプションパラメータは、同じブラウザ操作と紐付けて保持すること。ナビゲーションによってページが置き換えられたり、チャレンジが再生成されたりした場合は、次の試行を始める前に入力を再検査する。

実際の統合経路で結果を適用する

所有するアプリケーションが想定する方法で解答を使用し、その結果アプリケーションの挙動が意図どおりに変化したことを検証する。

トークンベースの結果は、見えている検証ボタンをクリックすべきという指示ではない。コールバックを使うアプリケーションもあれば、フォームに結果をバインドするものもあり、最終的なサーバー側検証も依然として重要である。JavaScript のコールバック名を推測するのではなく、アプリケーションの実装を確認すること。

Google の レスポンス検証ドキュメントは、reCAPTCHA のサーバー側検証ステップを説明している。ブラウザ自動化が「解答後のコード行」まで到達したからといって、そのサーバーがレスポンスを受け入れたことにはならない。

テストの成功条件は具体的に保つこと。自前フォームであれば、その確認画面やテストレコードを検査する。許可された読み取りワークフローであれば、期待されるコンテンツを検査する。ウィジェットが消えたことだけを完了シグナルとせず、アプリケーションが持つより信頼性の高い結果を確認する。

失敗をワークフロー全体の繰り返しなしで診断する

ナビゲーション、アカウントチェック、解答処理をまとめて再実行する前に、どのコンポーネントが失敗したかを診断する。

コンパイルエラーはコードと依存関係の互換性を示す。ブラウザ起動失敗は実行ファイルか実行環境を示す。キー欠如はページ検査を示す。サービスエラーはドキュメント化された API レスポンスを示す。解答後にフォームが拒否された場合は、結果の適用方法とアプリケーション本体が原因となりうる。

入力契約の不整合については、invalid-task-data トラブルシューティングガイド が、実際のリクエストと選択したタスクを比較する方法を示している。ブラウザのリトライを増やしても、そのリクエスト内のフィールドの綴りミスは修正されない。

パッケージバージョン、失敗ステージ、可能であればタスク ID、マスクしたエラー情報を含む小さな診断記録を保持すること。実際のアカウントキーや完全な解答トークンをログに残してはならない。エスカレーション時には、ブラウザチェックと API チェックがそれぞれ何を確認したかを説明する。

CapSolver で信頼性の高い自動化ワークフローを構築する

ブラウザ制御は chromedp に任せ、実際の CAPTCHA ステップでのみ、ドキュメント化されたソルバー呼び出しを挿入する。CapSolver は解答インターフェイスを提供し、ページ状態、エラー判断、最終的な完了チェックはアプリケーション側が責任を持つ。

FAQ

Q: chromedp は CAPTCHA 解答機能を内蔵していますか？

chromedp はブラウザコントローラである。このワークフローでは、許可されたタスク中に出現する対応チャレンジに対して、別のソルバーサービスを追加している。

Q: このサンプルはソルバークレジットを消費しますか？

有料タスクは作成されない。サンプルは、意図的に無効なプレースホルダーキーを使って残高リクエストを送り、その結果エラーを確認している。

Q: Go のエラーが nil なのに API がリクエストを拒否するのはなぜですか？

SDK は、サービスレベルのエラーを含むレスポンスを正常に受信・解析する場合がある。そのため、Go のエラーだけでなく、レスポンス内のエラーフィールドも確認する必要がある。

Q: FIXTURE_ONLY を自分の sitekey として使えますか？

使えない。これはブラウザ属性読み取りを確認するためのローカルテストデータである。実際の解答タスクには、許可されたページ上の最新の公開鍵が必要だ。

Q: ここで完全な有料 CAPTCHA 解答はテストされていますか？

いいえ。検証範囲は chromedp ブラウザフィクスチャと、実際の API 拒否レスポンスまでである。有料解答と、所有アプリケーションによる受け入れは、各自のアカウントと別個のエンドツーエンドテストを要する。