BrowserbaseでPlaywrightをクラウド接続する最短経路

ローカルで動いているPlaywrightのコードを、クラウドのブラウザ基盤に接続先だけ切り替えて動かす。それがBrowserbaseの使い方の核心です。

Playwright自体の書き方は既知として扱い、「ローカル実行と何が変わるのか」という差分に絞って説明します。

ローカルPlaywrightと何が違うのか：Browserbaseの立ち位置を整理する

Browserbaseを一言で言うと、クラウドホスト型のブラウザ実行基盤です。

PlaywrightやPuppeteerはクライアント側のオートメーションライブラリであり、Browserbaseはそのブラウザプロセスそのものをクラウド上で動かすインフラです。

ローカルでchromium.launch()を呼ぶとき、ブラウザプロセスはあなたのマシン上で起動します。

Browserbaseを使う場合、そのプロセスはBrowserbaseのサーバー上で起動し、あなたのコードはCDP（Chrome DevTools Protocol）経由でそこに接続します。Playwrightを捨てる必要はなく、接続先が変わるだけです。

ローカル実行との本質的な差分は4点あります。

• プロセス管理の外部化: ブラウザの起動・終了・クラッシュ時の再起動をBrowserbase側が担う。自前サーバーでのプロセス管理が不要になる
• 並列スケーリング: 複数セッションを同時に立ち上げる場合、ローカルではマシンリソースが上限になるが、Browserbaseではプランの範囲内でスケールできる
• フィンガープリント回避: ヘッドレスブラウザ特有のシグナルをBrowserbase側で処理し、ボット検出を受けにくくする
• セッションリプレイ: 実行したセッションの録画をダッシュボードで後から再生できる。headlessデバッグのコストが大きく下がる

近い競合としてはBrowserlessやSteel.devがあります。

どれもCDP接続でPlaywrightを動かすという基本モデルは同じで、差別化はセッション管理のAPI設計やAIエージェント連携にあります。BrowserbaseはStagehandというAI自動化SDKを自社で持っている点が特徴的です。

アカウント作成とAPIキー取得

Browserbaseの公式サイトからサインアップします。

メールアドレスとパスワードで登録後、電話番号によるSMS認証が求められます。電話番号認証で詰まった場合は、サポートポータルかsupport@browserbase.comへの連絡が公式の案内です。

サインアップ後のダッシュボードで取得すべきクレデンシャルが2つあります。API KeyとProject IDです。

この2つは別物です。API KeyはBrowserbase APIへの認証トークンで、Project IDはセッションをどのプロジェクトに紐付けるかを示す識別子です。後述するセッション作成のAPIコールでは両方が必要になります。

混同して片方しか設定しないのが、最初の認証エラーの主因です。ダッシュボードの「Settings」→「API Keys」でAPI Keyを発行し、「Settings」→「General」でProject IDを確認できます。

両方をコピーして.envに書いておきます。

BROWSERBASE_API_KEY=your_api_key_here
BROWSERBASE_PROJECT_ID=your_project_id_here

無料プランの実態も把握しておきます。公式ドキュメントによると、同時1セッション・月60分が無料枠の上限です。

評価目的であれば十分ですが、セッションを閉じ忘れると無料枠を消耗し続けます。この点は後のセクションで対処します。

• API Key: APIへの認証トークン。Settings → API Keysで発行
• Project ID: セッション作成時に必須の識別子。Settings → Generalで確認
• 無料枠の制約: 同時1セッション・月60分。セッション管理を怠ると静かに消耗する

SDKインストールとPlaywright接続の最小構成

Browserbase公式のNode.js SDKとPlaywrightをインストールします。

npm install @browserbasehq/sdk playwright

TypeScriptで書く場合はts-nodeと型定義も追加します。

npm install -D typescript ts-node @types/node

ローカルPlaywrightとBrowserbase接続の差分を並べると、変更点が一目でわかります。

// ローカルPlaywright（変更前）
import { chromium } from 'playwright';

const browser = await chromium.launch();
const page = await browser.newPage();
await page.goto('https://example.com');
console.log(await page.title());
await browser.close();

// Browserbase接続（変更後）
import { chromium } from 'playwright';
import Browserbase from '@browserbasehq/sdk';

const bb = new Browserbase({ apiKey: process.env.BROWSERBASE_API_KEY! });

const session = await bb.sessions.create({
  projectId: process.env.BROWSERBASE_PROJECT_ID!,
});

// 公式SDKのセッションレスポンスに含まれるCDP接続用URLを使用
// 実際のプロパティ名はSDKのレスポンス型定義を確認してください
const browser = await chromium.connectOverCDP(session.connectUrl);
const page = await browser.newPage();
await page.goto('https://example.com');
console.log(await page.title());
await browser.close();

chromium.launch()がchromium.connectOverCDP()に変わっています。それだけです。

接続モデルの差分を整理しておきます。

• launch vs connectOverCDP: ローカルはブラウザプロセスを起動するが、Browserbaseはすでに起動済みのリモートブラウザにCDPで接続する
• セッションIDの扱い: bb.sessions.create()が返すsession.idがBrowserbase上のセッション識別子。ダッシュボードでの確認やデバッグに使う
• ブラウザプロセスの所在: ローカルでは自マシン上。Browserbaseではクラウドサーバー上。ネットワーク遅延は発生するが、ブラウザ自体のリソース消費はゼロ

動作する最小スクレイピングコードを示します。dotenvでの環境変数読み込みも含めた完全な形です。

import { chromium } from 'playwright';
import Browserbase from '@browserbasehq/sdk';
import * as dotenv from 'dotenv';

dotenv.config();

async function main() {
  const bb = new Browserbase({
    apiKey: process.env.BROWSERBASE_API_KEY!,
  });

  const session = await bb.sessions.create({
    projectId: process.env.BROWSERBASE_PROJECT_ID!,
  });

  console.log('Session ID:', session.id);

  // session のCDP接続URLプロパティ名はSDKの型定義を参照してください
  const browser = await chromium.connectOverCDP(session.connectUrl);

  try {
    // リモート接続時はBrowserbaseがコンテキストを用意済み
    const context = browser.contexts()[0];
    const page = context.pages()[0];

    await page.goto('https://example.com');
    const title = await page.title();
    console.log('Page title:', title);
  } finally {
    await browser.close();
  }
}

main().catch(console.error);

connectOverCDP後のコンテキスト取得はbrowser.newContext()ではなくbrowser.contexts()[0]を使います。

リモート接続時はBrowserbaseがすでにコンテキストを用意しているため、新規作成ではなく既存のものを取得します。実行はnpx ts-node index.tsで動きます。コンソールにセッションIDとページタイトルが表示されれば成功です。

実行結果の確認とハマりやすいポイント

実行が終わったらダッシュボードの「Sessions」タブを開きます。

実行したセッションが一覧に表示されており、クリックするとSession Inspectorに入れます。

Session Inspectorでは、セッションの録画（セッションリプレイ）・ネットワークログ・コンソールログを確認できます。

「何をクリックしたか」「どのリクエストが飛んだか」がブラウザの動作として視覚的に確認できるため、ローカルのheadlessデバッグより格段に楽です。セッションIDがわかっていればhttps://www.browserbase.com/sessions/<session_id>で直接アクセスすることもできます。

ハマりやすいポイントは3つあります。

1. API KeyとProject IDの混同

最も多い初期エラーです。401 Unauthorizedが返ってきたらまずここを疑います。

API Keyはnew Browserbase({ apiKey: ... })に渡し、Project IDはsessions.create({ projectId: ... })に渡します。環境変数名をBROWSERBASE_API_KEYとBROWSERBASE_PROJECT_IDで明確に分けておくと混同を防げます。

2. タイムアウト

ネットワーク遅延が加わるリモート接続では、page.goto()のデフォルトタイムアウトが想定より短く感じることがあります。

page.goto(url, { timeout: 30000 })のように明示的に指定しておくのが無難です。

3. セッション未クローズによる無料枠の消耗

browser.close()を呼ばずにプロセスが終了すると、セッションがBrowserbase側でタイムアウトするまで時間がカウントされ続けます。

try/finallyでcloseを確実に呼ぶのが基本です。

const browser = await chromium.connectOverCDP(session.connectUrl);

try {
  const context = browser.contexts()[0];
  const page = context.pages()[0];

  await page.goto('https://example.com');
  console.log(await page.title());
} finally {
  // エラーが起きても必ずcloseを呼ぶ
  await browser.close();
}

finallyブロックにbrowser.close()を置くことで、途中でエラーが発生してもセッションが確実に終了します。無料枠の節約だけでなく、本番環境でのリソースリークを防ぐためにも徹底しておきたいパターンです。

実プロジェクトへの適用をどう判断するか

正直に言うと、単発の動作確認や月数回の定期取得程度であれば、ローカルのPlaywrightで十分です。Browserbaseの価値が出てくるのは、ローカル実行でインフラ的な問題にぶつかり始めたときです。

具体的には、複数URLを同時にスクレイピングしたい・ジョブキューからブラウザタスクを並列実行したい、といった場面でローカルはマシンリソースが天井になります。ボット検出の厳しいサイトを対象にするケースでも、フィンガープリント処理をBrowserbase側に任せられる恩恵は大きいです。

Dockerでブラウザを動かすCI/CDの維持、クラッシュ時の再起動、バージョン管理といった運用コストを手放したい場合も、採用を検討する理由になります。

採用を検討すべき条件をまとめると以下の通りです。

• 並列スケールが必要: 複数セッションを同時実行したい
• フィンガープリント対策が要る: ボット検出の厳しいサイトを対象にしている
• ブラウザインフラを自前管理したくない: CI/CDのブラウザ運用コストを手放したい

逆に、以下であればローカルで十分です。

• 単発・小規模: 開発中の動作確認、1〜2並列で足りるタスク
• 既存コードが安定稼働中: インフラ的な課題がなければ移行する理由は薄い

既存のPlaywright資産の移行コストは小さく、接続部分の数行を書き換えるだけでページ操作のコードはそのまま動きます。「まず評価してみる」のハードルは低く、無料枠の60分で十分試せます。Contexts APIを使ったブラウザ状態の再利用や、StagehandによるAIエージェント連携は、セッションが動いてから考えれば十分です。

---

株式会社ホコサキは、山口県宇部を拠点にWeb制作・業務システム開発・AI活用支援・DX推進に取り組んでいます。Browserbaseのような新しい開発ツールの評価・導入支援も対応しています。お気軽にお問い合わせください。