Chrome 拡張機能

extensions を使うと、起動時にパッケージ化されていない拡張機能を読み込めます。Manifest V2 と V3 のどちらも、ヘッドありでもヘッドレスでも、Windows と Linux で動作します。

読み込み方

launch()、launch_persistent_context()、serve() に、パッケージ化されていない拡張機能のディレクトリ（それぞれ manifest.json を含むフォルダ）のリストを渡します（.NET では Extensions = new[] { ... }）。拡張機能はブラウザのプロファイルに読み込まれるため、使えないのはシークレットモードでの起動（ephemeral_profile=False、非同期 API の launch()、.NET の LaunchAsync）だけです。拡張機能は SDK で起動したブラウザ向けの機能で、ホスト型ブラウザでは読み込まれません。

python

from clearcote import launch_persistent_context

ctx = launch_persistent_context(
    "./profile",
    extensions=["./ext/ublock", "./ext/my-helper"],   # unpacked directories
)
page = ctx.pages[0] if ctx.pages else ctx.new_page()
page.goto("https://example.com")

javascript

import { launchPersistentContext } from "clearcote";

const ctx = await launchPersistentContext("./profile", {
  extensions: ["./ext/ublock", "./ext/my-helper"],
});

SDK は --load-extension と --disable-extensions-except の両方を自動で設定します。この組み合わせが重要です。--load-extension だけでは自動化の下では無視されてしまい、拡張機能がエラーもなく表示されない原因は、たいていこれです。

展開済みディレクトリを用意する

Clearcote が読み込むのはフォルダで、.crx ファイルではありません。.crx は署名ヘッダー付きの ZIP なので、展開すれば読み込み可能なディレクトリになります：

bash

unzip extension.crx -d ./ext/extension

Clearcote は Chrome ウェブストアから拡張機能をインストールしたり更新したりできません。アップストリームのプライバシーパッチがその連携を取り除いているためです。展開済みのディレクトリを自動化のコードと一緒に配布し、更新は自分で行ってください。この方法で読み込んだ拡張機能が自動で更新されることはありません。Playwright や Puppeteer と同じ方式です。

Manifest V2 も引き続き動作します

標準の Chrome では、Manifest V2 の拡張機能はもう動作しません。Clearcote では引き続き動作します。アップストリームのプライバシーパッチセットがそのサポートを復元しているためです。そのため、MV2 専用のコンテンツブロッカーや古い社内ツールも、Chrome で動かなくなった後もここでは動き続けます。

python

# both of these load and run
ctx = launch_persistent_context("./profile", extensions=["./ext/mv2-tool", "./ext/mv3-tool"])

ヘッドレス

拡張機能は、ヘッドありモードだけでなくヘッドレスモードでも読み込まれます。追加のフラグは不要で、拡張機能を動かすためだけにディスプレイサーバーを起動する必要もありません。

python

ctx = launch_persistent_context("./profile", extensions=["./ext/my-helper"], headless=True)

フィンガープリント上の注意点

拡張機能はあなたのプロファイルで動くあなたのコードであり、Clearcote はそれを隠しません。ここから 2 つのことが言えます。どちらも、後から気づくのではなく、意図して判断しておくべきことです。

拡張機能は観測できます。DOM を書き換えたり、スタイルを注入したり、リクエストをブロックしたりするコンテンツスクリプトは、ページが計測する内容を変えます。現在のマークアップを自分が配信したものと比較するサイトは、何かがページを改変したことに気づけます。これは拡張機能を入れたあらゆるブラウザに当てはまり、Clearcote 固有のシグナルではありませんが、シグナルであることに変わりはありません。
Web アクセス可能なリソースは探知できます。拡張機能が web_accessible_resources を宣言していると、どのページでも chrome-extension://<id>/<file> の取得を試みて、その拡張機能が入っていることを知ることができます。何も宣言していない拡張機能を選び、宣言が必要なものでは use_dynamic_url を念頭に置いてください。

目的が UI の提供ではなくリクエストのブロックなら、自動化レイヤーで CDP の Network.setBlockedURLs を使うことを検討してください。URL パターンでブロックでき、拡張機能のサーフェスが増えず、ブラウザキャッシュも保たれます（Playwright の page.route() でも可能ですが、キャッシュが無効になります）。一般的な原則（偽装は必要なものだけにとどめ、サーフェスは追加に見合うものだけを加える）については推奨設定を参照してください。

トラブルシューティング

何も起きない。パスが親フォルダや .crx ではなく、manifest.json を含むフォルダを指しているか確認してください。
コンテンツスクリプトが実行されない。matches のパターンが、アクセスしている URL をカバーしているか確認してください。たとえば http://localhost/* は http://127.0.0.1:8080/ にマッチしません。
ヘッドありでは動くが、ヘッドレスでは動かない。このビルドでは起こらないはずの現象で、どちらでも動作します。遭遇した場合は、マニフェストを添えて issue を作成してください。