Lightpanda クローラーを CAPTCHA ソルバー API に接続する方法

要約

• Lightpanda はヘッドレスブラウザを提供し、別の CAPTCHA API が、許可されたワークフロー内でサポートされているチャレンジの結果を返します。
• Puppeteer を Lightpanda の CDP エンドポイントに接続し、ソルバーリクエストを組み立てる前に実際のページを確認します。
• reCAPTCHA v2 では、現在のページ URL、公開サイトキー、およびそのチャレンジで必要とされる追加パラメータ（ドキュメント記載のもの）を使用します。
• ソルバーが動作している間は、元のページを開いたままにしておきます。レスポンストークンは、正しいアプリケーションのコールバックまたは送信経路に届く必要があります。
• ブラウザ接続テストは、CAPTCHA スクリプトの互換性や最終的なサイト側の受け入れを証明するものではありません。これらは必ず、許可されたテストページで別途検証してください。

Lightpanda は、オートメーション、クローリング、テスト、ブラウザエージェント向けに構築されたヘッドレスブラウザです。開発者は主に Puppeteer などを通じて Chrome DevTools Protocol（CDP）のようなインターフェースから制御します。HTTP レスポンスだけではワークフローに必要な情報が含まれない場合でも、ページの JavaScript 実行や DOM の検査ができるため有用です。

CAPTCHA は別工程です。Lightpanda でページを読み込んだからといって、その検証チャレンジが完了したとは限りません。CapSolver は、サポートされている CAPTCHA 向けにドキュメント化されたソルバー API を提供しますが、ページ状態と最終結果の管理は、あくまであなたのアプリケーション側の責任です。

本ガイドは、すべての CAPTCHA ページが Chromium と同じ挙動をすると仮定せずに、こうした責務を結びつけます。実行可能なサンプルはブラウザ接続を検証するだけです。ソルバーリクエストとアプリケーション側での受け入れには、あなた自身の認証情報と許可されたチャレンジが必要です。

2 つの接続を理解する

Lightpanda の CAPTCHA 連携では、ブラウザへの接続と、アプリケーションのバックエンドからソルバー API への接続という 2 つが必要になります。

Lightpanda リポジトリには、Puppeteer が CDP エンドポイントに接続する様子が示されています。ブラウザのナビゲーション、ページ検査、アプリケーションのコールバックは、ワークフローのこの側で完結します。CapSolver のタスク API は、タスク固有の入力を受け取り、タスクのレスポンスを返します。

ソルバー API へのリクエストを CDP ポートに送らないでください。また、ブラウザの WebSocket URL を websiteURL として送ることもやめてください。一方はブラウザプロセスを制御するアドレスであり、もう一方は CAPTCHA を読み込むウェブページを指す URL です。

API コントラクトは、連携側が知りうる範囲も定義します。ソルバー結果は、「すべてのブラウザ操作を自動的に再開させるコマンド」ではありません。アプリケーションは、返却されたフィールドを、そのページが期待する方法で利用しなければなりません。

ブラウザのインストールと起動

有料のソルバーリクエストを投げる前に、隔離されたプロジェクトフォルダに Lightpanda と Puppeteer をインストールします。

接続例では、Lightpanda 1.0.2、Puppeteer Core 25.16.0、Node.js 24 を使用します。Node 依存パッケージは npm install --save-exact puppeteer-core@25.16.0 でインストールします。お使いの OS / CPU 向けバイナリを公式 1.0.2 リリースからダウンロードし、実行権限を付与してから ./lightpanda version でバージョンを確認してください。

ローカル CDP サーバーは ./lightpanda serve --host 127.0.0.1 --port 9227 で起動します。クライアントが接続している間、このターミナルを開いたままにしておきます。以下の例で使用するポート番号は、サーバー側と一致させてください。開発環境ではローカルバインドを使用します。

先に許可されたテストページを用意しておきましょう。最初の接続確認であれば、あなたが所有する簡単なページで構いません。その後の CAPTCHA テストでは、実際のチャレンジと、アプリケーション側で受け入れ結果を観測できる仕組みを持つページが必要になります。また、有効な CapSolver API キーと残高も、有料タスクを作成する前に準備してください。

本ガイドでは、有料ソルブの実行例は示しません。検証済みブラウザのステップと、API 認証レスポンスは、それぞれの「接続面」を確認するものです。特定の外部サイトに対する CAPTCHA ソルブの成功や互換性を保証するものではありません。

Puppeteer から Lightpanda への接続を検証する

AUTHORIZED_TEST_URL をテストページの URL に設定し、次の内容を lightpanda-connect.mjs として保存して node lightpanda-connect.mjs を実行します。

この例は、Lightpanda の公式 Puppeteer 接続パターンをもとにしています。ブラウザコンテキストを作成し、許可されたページを読み込み、そのタイトルと最終 URL を取得したあと、コンテキストとクライアント接続をクリーンアップします。

import puppeteer from 'puppeteer-core';

const target = process.env.AUTHORIZED_TEST_URL;
if (!target) throw new Error('Set AUTHORIZED_TEST_URL to your permitted test page');
const browser = await puppeteer.connect({
  browserWSEndpoint: 'ws://127.0.0.1:9227',
});
try {
  const context = await browser.createBrowserContext();
  try {
    const page = await context.newPage();
    await page.goto(target, { waitUntil: 'domcontentloaded' });
    console.log({ title: await page.title(), url: page.url() });
  } finally {
    await context.close();
  }
} finally {
  await browser.disconnect();
}

出力には、実際に読み込まれたページが判別できる情報が表示されるはずです。エラーページやリダイレクト、無関係なドキュメントが出ている場合は、CAPTCHA リクエストを組み立てる前に修正してください。シンプルなテストページ上で JavaScript が正常に実行されることは有用な出発点ですが、実際のウィジェットに必要なブラウザ API がすべてサポートされていることの証明にはなりません。

Puppeteer の connect リファレンスは、既存ブラウザへのアタッチについて説明しています。このため、例では別の Chromium プロセスを起動するのではなく connect を使っています。テスト対象のプロセスはあくまで Lightpanda である必要があるからです。

ドキュメントに沿った CAPTCHA タスクを 1 つ用意する

ブラウザが実際に読み込んだチャレンジからソルバータスクを構築し、その入力をページと紐づいた状態に保ちます。

標準的な reCAPTCHA v2 については、公式 v2 タスクリファレンスから始めてください。プロキシを使わないリクエストであれば、ReCaptchaV2TaskProxyLess、websiteURL、websiteKey を使用します。他に観測されたパラメータは、ドキュメントに記載されたフィールドに配置します。画面上のチェックボックスだけから値を推測してはいけません。

以下の JSON は、そのリクエスト構造を例示したものです。プレースホルダを含んでおり、実際のチャレンジでも実行された有料リクエストでもありません。値はあなたの許可されたページに合わせて置き換え、送信には上記リンクの公式 API / SDK サンプルを利用してください。

{
  "clientKey": "YOUR_API_KEY",
  "task": {
    "type": "ReCaptchaV2TaskProxyLess",
    "websiteURL": "https://example.com/authorized-form",
    "websiteKey": "PUBLIC_SITE_KEY_FROM_THIS_PAGE"
  }
}

clientKey はバックエンドプロセスに保持してください。これはブラウザ側に埋め込むサイトキーではなく、ページに挿入すべきものでもありません。websiteURL は CAPTCHA を読み込むウェブページ自体を表すものであり、CAPTCHA iframe の URL や Lightpanda の制御エンドポイントを指してはいけません。

バージョンや追加パラメータが分からない場合は、許可されたページを検査しながら、ドキュメント化されたCAPTCHA パラメータ検出ワークフローを利用してください。これは準備ステップであり、「Chrome 拡張機能を Lightpanda に読み込める」という意味ではありません。

CapSolver ボーナスコードを利用する

自動化予算を今すぐ増強しましょう！
チャージ時にボーナスコード CAP26 を使用すると、すべてのリチャージで追加 5% ボーナス を無制限に獲得できます。
今すぐ CapSolver ダッシュボード から利用してください。

ページを置き換えずにソルバー結果を取得する

タスク API が完了するまで、Lightpanda 上のページとそのアプリケーション状態を維持します。

非同期レスポンスの場合は、createTask によって返されたタスク ID を保持し、そのタスクに対して getTaskResult を使用します。ソリューションを読む前に、API エラーと処理状態を確認してください。v2 結果でレスポンストークンが格納されるフィールド名は、ドキュメント上では gRecaptchaResponse です。

ソルバーリクエストが完了したという理由だけで、新しいブラウザコンテキストを作らないでください。新しいコンテキストは別のページ環境であり、アプリケーション側には元の操作に紐づく状態が残っているかもしれません。同様に、「同じ種類のウィジェットが表示されているから」といった理由で、別ページの保留中チャレンジに結果を使い回すべきではありません。

先ほどの「接続のみ」のスクリプトでは、コンテキストを明示的にクローズしています。実アプリケーションにソルバー実行を統合する場合は、ソルバー処理とページ固有の継続処理を、このコンテキストの存続期間内（クリーンアップが走る前）に配置してください。エラー時にもクリーンアップが行われるように維持してください。

アプリケーション側が所有するトークン受け渡しを使う

結果は、あなたのアプリケーションが定義したコールバックまたは送信経路を通して適用してください。あらゆるページで通用する「共通のコールバック名」は存在しません。名前を推測して統合に貼り付け、「フォームが値を受け入れたはずだ」と仮定すべきではありません。

最小限のブラウザ側アダプタは、まず手元のフィクスチャ（検証用ページ）上で、不活性な文字列を使って確認できます。想定されたコールバックがその文字列を受け取り、関連フィールドが変化することを確かめましょう。これはあくまでアダプタの検証であり、その不活性文字列を有効な CAPTCHA 応答として送信してはなりません。

Google の reCAPTCHA 応答検証ガイドは、アプリケーション側の検証ステップを別途説明しています。本物のソルバー結果をハンドオフしたあと、同じ試行に対するアプリケーションの結果を確認してください。フィールドが埋まっている、あるいはコールバックが完了したというだけでは十分な証拠になりません。

どのコンポーネントが失敗したかで原因を切り分ける

ブラウザ読み込み、ソルバー実行、アプリケーション側の受け入れを分けて考え、リトライ時には実際の問題箇所を対象にします。

Puppeteer が接続できない

Lightpanda プロセスがまだ動作しているか、ホストとポートが一致しているかを確認します。Chromium 用スクリプトが動いているからといって、同じものが現在の Lightpanda ビルドでも互換性があると決めつける前に、固定バージョンのクライアントとブラウザを確認してください。

ページは読み込まれるが CAPTCHA ウィジェットが出ない

ページスクリプトのエラーと、ウィジェットのネットワークリクエストを確認します。ソルバー API は、ページが要求するブラウザエンジン機能を修復することはできません。許可されたページで期待されるチャレンジが正しく読み込まれることを、有料タスクに進む前に証明してください。

タスク API がリクエストを却下する

ドキュメントに記載されたエラーレスポンスを読み、キー、タスクタイプ、URL、サイトキー、条件付きフィールドを確認してください。認証エラーが返っているのであれば、「API が応答した」ことは分かっても、「連携が成功した」ことは証明されません。同じ不正入力を繰り返し送信しないでください。

ソルバーがトークンを返すが、アプリケーションが拒否する

ページ所有権、トークンの受け渡し、コールバックの挙動、サーバー側検証を確認します。タスク ID と伏せ字化した失敗理由を記録してください。共有ビルド出力に API キーや生のレスポンストークンをログとして残さないようにします。

フィクスチャでしかワークフローが動かない

フィクスチャはあくまでアダプタテストとして扱ってください。実際に許可された CAPTCHA フローを実行し、統合に依存できるか確認します。ブラウザの挙動、ウィジェットスクリプト、アプリケーション側検証はいずれも追加条件であり、CDP ハンドシェイクが成功したからといって自動的に満たされるものではありません。

この統合がクローラに適しているか判断する

Lightpanda と外部ソルバー API の組み合わせが意味を持つのは、クローラがすでに Lightpanda を利用しており、許可されたタスク中にサポート対象 CAPTCHA に遭遇し、同じページの処理を継続する正当な方法を備えている場合です。CAPTCHA のないページにソルバーを追加したり、あらゆるブラウザとの互換性を主張したりする理由にはなりません。

まずは実際のブラウザ接続から始め、タスクスキーマを検証し、許可されたアプリケーションフローを 1 つテストしてから並列度を上げてください。各結果をリクエスト元ページと紐づけ、アプリケーション側の実際の結果を計測しましょう。

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

検証済み CAPTCHA チェックポイントでソルバーを利用し、その後アプリケーションの結果を確認してください。CapSolver は、このステップ向けにドキュメント化されたソルバーインターフェースを提供します。統合を拡張する前に、許可されたテストワークフローで CapSolver を試してください。

FAQ

Q: これは Lightpanda の内部に CAPTCHA ソルバーをインストールするのですか？

いいえ。アプリケーションは CDP を通じて Lightpanda と通信し、別途外部ソルバー API を呼び出します。そのうえで、許可されたアプリケーションが期待するフローに従って結果を適用する必要があります。

Q: CapSolver の Chrome 拡張をこのブラウザに読み込めますか？

このチュートリアルでは、Lightpanda における Chrome 拡張機能のサポートを前提にしていません。使用しているのは外部タスク API です。サポートされた Chrome 環境でのパラメータ検査は、別個の準備ステップです。

Q: Puppeteer で接続できれば、Lightpanda で reCAPTCHA が動くと証明できますか？

いいえ。接続でき、示されたブラウザ操作を実行できることを証明するだけです。実際の CAPTCHA スクリプトとアプリケーション側での受け入れについては、別途テストが必要です。

Q: JSON の例が使っている reCAPTCHA の種類は何ですか？

ReCaptchaV2TaskProxyLess による標準的な reCAPTCHA v2 を例示しています。Enterprise、v3、その他のチャレンジファミリーには、それぞれドキュメント化されたタスクタイプと入力が必要です。

Q: サンプルコードで有料 CAPTCHA ソルブは完了していますか？

いいえ。実行可能サンプルはブラウザ接続のみを確認し、JSON はプレースホルダ付きでタスク形状を説明しているだけです。ソルブと最終的な受け入れをテストするには、有効なソルバーアカウントと、許可されたライブチャレンジが必要です。