他人のページを書き換える — ブラウザ拡張を作る

ブラウザ拡張を作る。ブラウザ画面に付いたパズル部品と読了時間を表す時計。

ブラウザ拡張は、他人のページを自分の画面で書き換える仕組みです。manifest・content script・backgroundの3つで作ります。

前回: npm publish は取り消せない — CLIツールを配る

この記事は、いつもと作業場所が違います。 最初から最後まで、ホストの Windows で動いているブラウザの中だけで完結します。VMには GUI が無いので、VMの中では出来ません。 SSH も nginx も使いません。

DOM操作の回で、こう書きました。

document.querySelector('#result').textContent = 'こんにちは';

自分で書いた HTML を、自分の JavaScript で書き換えました。 ここまでは当たり前です。自分のページなのだから、好きにしていい。

では、こう考えてみてください。

同じ1行を、他人のサイトを開いた状態の開発者ツールで打つと、どうなるか。

動きます。 開発者ツールの回でコンソールを開いた、あの画面です。ニュースサイトを開いて document.body.style.background = 'red' と打てば、真っ赤になります。誰のサイトでも。

なぜ動くのか。 表示されている時点で、そのページの HTML と CSS と JavaScript はもう自分のPCの中に届いているからです。ブラウザは受け取ったものを組み立てて見せているだけで、組み立てたあとの DOM は、こちら側の持ち物です。

ただし、コンソールで打った変更はリロードすると消えます。 毎回打ち直すのは無理です。

「他人のページを開いたときに、自動で、毎回、その1行を打つ」 ——これが出来る仕組みが、ブラウザ拡張です。

拡張とは、他人のページに自分の JavaScript を差し込む正式な入口です。

だから便利で、だから危険です。 広告を消せるということは、入力欄の中身も読めるということです。この2つは同じ力の裏表で、切り離せません。

この記事では、その力を最小の形で1回だけ使って、何が出来て何が怖いのかを、作る側から確かめます。ストアには出しません。 審査もお金も時間もかかりますし、そこは今回の目的ではありません。自分のブラウザに読み込んで、自分だけが使うところで終わりにします。

対象レベル: 中級 / 区分: 必修

目次

この記事でわかること

  • 拡張は「ブラウザの機能追加」ではなく、他人のページに自分のスクリプトを差し込む仕組みだということ
  • 中身は3つしかないこと(manifest.json / コンテンツスクリプト / バックグラウンド)。それ以上は覚えなくていいこと
  • インストール時の権限画面が怖い理由。<all_urls> を付けた拡張は、パスワード欄の中身も読めること
  • 保存しても反映されないのが普通で、読み込み直しが要ること。これを知らないと最初の30分が溶ける
  • バックグラウンドは常駐しないこと。PWAの回で書いた Service Worker が、ここでも同じ制約ごと出てくること
  • chrome.storage と localStorage は別物であること。他人のサイトの localStorage を汚してはいけないこと
  • 他人のページを触るときの作法。既存の CSS を巻き込まないこと。読み込みが終わる前に触らないこと
  • 拡張は自動更新されること。作者が変わっても、同じIDのまま更新が降ってくること
  • Firefox とはほぼ同じ manifest.json で動くが、細部が違うこと

この記事でやること

  1. フォルダを1つ作り、manifest.json と content.js の2ファイルだけ置く
  2. Chrome の開発者モードで「パッケージ化されていない拡張機能を読み込む」(山場)。読了時間バッジが右上に出るところまで
  3. matches を書き換えて、動くサイトを絞る。 権限画面がどう変わるかを見る
  4. バックグラウンド(Service Worker)を足して、常駐しないことを目で確かめる
  5. chrome.storage で設定(1分あたりの文字数)を保存する
  6. 拡張を削除して、元に戻す(後片づけ。必ずやります)

先に知る言葉

この記事で初めて出てくる言葉です。 基本的な言葉は用語集にもまとめてあります。

言葉意味
拡張機能(extension)ブラウザに後から入れる小さなプログラム。普通のWebページと同じ HTML・CSS・JavaScript で書く。新しい言語は要らない
manifest.json拡張の身分証明書。名前・バージョン・どのサイトで動くか・何をする権限が要るかを宣言する1ファイル。これが無いと拡張として認識されない
Manifest V3(MV3)manifest.json の書き方の世代。現在の Chrome はこれ。古い記事は V2 で書かれていて、そのままでは動かない
コンテンツスクリプト他人のページの中に注入される JavaScript。DOM を触れるのはこれだけ
バックグラウンド(Service Worker)ページとは別に、裏で動くスクリプト。DOM は触れない。用が無いと止まる
matches(マッチパターン)どのURLでコンテンツスクリプトを動かすかを書く指定。https://example.com/* のような形
permissions拡張が要求する権限の一覧。インストール時に利用者へ見せられるのはここ
<all_urls>「すべてのサイト」を表す特別な書き方。一番強く、一番付けてはいけないもの
Shadow DOM要素の中に外から隔離された小さなDOMを作る仕組み。中の CSS は外に漏れず、外の CSS も入ってこない。Web Components の回で出てきたもの
サイドロードストアを経由せず、フォルダや zip から直接入れること。今回やるのはこれ

拡張の中身は、3つしかない

拡張の解説を読むと、ポップアップ、オプションページ、コンテキストメニュー、DevTools パネル……と部品が並んでいて、最初にここで諦めます。

でも、本体は3つです。 残りは全部、この3つの上に乗っているおまけです。

部品どこで動くかDOM を触れるか役割
manifest.json動かない(設定ファイル)—何をする拡張なのかを宣言する。 ブラウザはこれだけを見て権限を決める
コンテンツスクリプト開いている他人のページの中触れる実際にページを書き換える。拡張の「手」
バックグラウンド(Service Worker)ページの外(拡張だけの場所)触れない通信・保存・タブをまたぐ処理。拡張の「頭」

押さえどころは1つだけです。

DOM を触れるのはコンテンツスクリプトだけ。ネットワークや保存を任せたいならバックグラウンド。この2つは別の場所で動くので、直接は変数を共有できない。

今回作るバッジはページを書き換えるだけなので、最初はコンテンツスクリプトだけで作ります。 バックグラウンドは後半で足します。

作るもの: 読了時間バッジ

「このページ、読むのに何分かかるか」を右上に出すだけの拡張です。

やることは、本文の文字数を数えて、1分あたりの文字数で割る。それだけです。ネットワークにも行きませんし、何も保存しません。一番弱い拡張を、わざと選んでいます。

弱いものから始める理由は、権限を後から1つずつ足していく実験がしたいからです。強い拡張から始めると、何がどの権限のせいなのか分からなくなります。

フォルダとファイルを作る

ここからは Windows 側の PowerShellです。VMの中ではありません。

PowerShell
PS> mkdir "$HOME\Desktop\reading-time-badge"
PS> cd "$HOME\Desktop\reading-time-badge"

このフォルダの中に、ファイルを2つ作ります。VS Code で開くのが楽です。

PowerShell
PS> code .

1枚目: manifest.json

まずこれです。 拡張の身分証明書で、これが無いと読み込みすら出来ません。

{
  "manifest_version": 3,
  "name": "読了時間バッジ",
  "version": "1.0",
  "description": "開いているページの文字数から、読むのにかかる時間を計算して右上に出します。",
  "content_scripts": [
    {
      "matches": ["https://obmes.com/*"],
      "js": ["content.js"],
      "run_at": "document_idle"
    }
  ]
}

1行ずつ見ます。ここが記事の中で一番大事な部分です。

キー意味
manifest_version3 固定。2 と書くと今の Chrome は読み込みません。古い記事をそのまま写すとここで詰まります
name / version / description拡張管理画面に出る文字。version は数字とピリオドだけ(1.0 や 1.0.2)。v1.0 と書くとエラーになります
content_scripts配列です。「このURLで、このJSを、このタイミングで動かす」の組を並べます
matchesこれが「どのサイトで動くか」。 今回は自分がよく読むサイト1つに絞りました
js差し込むファイル名。フォルダの中の相対パスです
run_atいつ差し込むか。 後述します

permissions を書いていないことに注目してください。 DOM を書き換えるだけなら、追加の権限は要りません。 matches に書いたサイトへのアクセスだけで足ります。

matches の書き方

ここを雑に書くと、そのまま「怖い拡張」になります。 形は決まっています。

スキーム :// ホスト / パス
書き方意味評価
https://obmes.com/*このドメインの全ページ✅ これが基本
https://obmes.com/roadmap/*このドメインの /roadmap/ 以下だけ✅ さらに良い
https://*.example.com/*サブドメインも全部必要なときだけ
*://*/*全サイト(http も https も)❌ ほぼ常に不要
<all_urls>全サイト(file:// なども含む)❌ 一番強い。安易に付けない

よくある間違いが2つあります。

  • スキームを書き忘れる。 obmes.com/* と書くと、読み込むときに Invalid match pattern で弾かれます
  • 末尾の /* を忘れる。 https://obmes.com だけだと、パスの指定が無いのでこれもエラーです。「ドメインのトップだけ」ではなく、単に不正です

run_at は3つある

「読み込みが終わる前に触ると壊れる」 ——これは DOM操作の回で踏んだ Cannot read properties of null と、まったく同じ話です。他人のページなら、なおさら当たります。

値いつ動くか使いどころ
document_startHTMLを読む前。DOM はほぼ空ページより先に何かを仕込みたいとき(上級)
document_endHTMLを読み終えた直後。画像はまだDOM は触れる
document_idle読み込みが落ち着いてから(省略時はこれ)✅ 迷ったらこれ。今回もこれ

document_idle を指定しておけば、document.body が null で落ちることは、まず起きません。

2枚目: content.js

ここが実際に他人のページを書き換える部分です。同じフォルダに content.js を作ります。

const HOST_ID = 'reading-time-badge-host';
const CHARS_PER_MINUTE = 500;

function countCharacters() {
  const main =
    document.querySelector('article') ||
    document.querySelector('main') ||
    document.body;
  const text = main.innerText || '';
  return text.replace(/\s+/g, '').length;
}

function showBadge(minutes, chars) {
  if (document.getElementById(HOST_ID)) return;

  const host = document.createElement('div');
  host.id = HOST_ID;
  host.style.position = 'fixed';
  host.style.top = '12px';
  host.style.right = '12px';
  host.style.zIndex = '2147483647';

  const root = host.attachShadow({ mode: 'open' });

  const style = document.createElement('style');
  style.textContent =
    '.badge{font:13px/1.4 sans-serif;background:#1f2937;color:#fff;' +
    'padding:6px 10px;border-radius:6px;opacity:0.92}';

  const box = document.createElement('div');
  box.className = 'badge';
  box.textContent = '読了 約' + minutes + '分 / ' + chars + '文字';

  root.append(style, box);
  document.body.appendChild(host);
}

const chars = countCharacters();
const minutes = Math.max(1, Math.round(chars / CHARS_PER_MINUTE));
showBadge(minutes, chars);

30行しかありません。 そして、知らない書き方は1つも出てきていないはずです。 querySelector も createElement も textContent も、DOM操作の回でやったものです。

拡張だからといって、新しい言語も新しいAPIも要りません。 違うのは動く場所だけです。

3つだけ補足します。

  • innerText を使っています。 textContent だと、CSS で隠されているメニューやスクリプトの中身まで数えてしまいます。innerText は画面に見えている文字を返します。ここは textContent より innerText が正解の、数少ない場面です
  • replace(/\s+/g, '') で空白と改行を落としています。 日本語の文字数を数えるとき、インデントの空白まで数えると倍近くずれます
  • Math.max(1, ...) を噛ませています。 短いページで「0分」と出ると、壊れているように見えるためです

なぜ innerHTML を使っていないのかは、後の「作法」の節でまとめます。

ブラウザに読み込む

ここからは Windows の Chrome の画面です。コマンドは打ちません。

  1. Chrome のアドレス欄に chrome://extensions と入れて開く
  2. 右上の 「デベロッパー モード」をオンにする
  3. 左上に現れる 「パッケージ化されていない拡張機能を読み込む」 を押す
  4. さっき作った reading-time-badge フォルダを選ぶ(manifest.json ではなく、フォルダごとです)

[スクリーンショット: 01_デベロッパーモード.png] chrome://extensions を開いて、右上の「デベロッパー モード」をオンにした直後の画面を撮ってください。左上に3つのボタンが出ているところが写るようにしてください。

うまくいくと、カードが1枚増えます。 これが読み込まれた拡張です。

[スクリーンショット: 02_読み込んだ拡張.png] 読み込みに成功して「読了時間バッジ 1.0」のカードが出ている状態を撮ってください。

この状態で、matches に書いたサイト(この記事どおりなら https://obmes.com/ のどれかのページ)を開きます。

右上に黒い小さな箱が出れば成功です。

[スクリーンショット: 03_バッジ表示.png] 記事ページの右上に「読了 約◯分 / ◯◯◯◯文字」のバッジが出ているところを撮ってください。

他人が作ったページの右上に、自分が書いた要素が乗っています。 サーバーには一切触っていません。届いたあとに、こちらで足しただけです。これが拡張の全部です。

出なかったとき

ほぼこの3つのどれかです。

症状原因直し方
カードに赤い「エラー」ボタンが出るmanifest.json の書き方ボタンを押すと理由が出ます。Invalid match pattern なら matches のスキーム忘れ
カードは出るがバッジが出ないmatches と、いま開いているURLが合っていないアドレス欄のURLと matches を見比べる
バッジも出ず、エラーも無いcontent.js の中で落ちているそのページで F12 を開き、Console タブを見る

3つ目が大事です。 コンテンツスクリプトのエラーは、拡張の管理画面ではなく、そのページの開発者ツールに出ます。 ページの中で動いているからです。管理画面ばかり見て「何も出ない」と悩むのが定番です。

保存しても、変わりません

ここで必ず1回は詰まります。 断言できます。

content.js を書き換えて保存し、ページをリロードします。何も変わりません。 もう一度保存します。変わりません。コードを疑い始めます。ここで20分溶けます。

拡張は、読み込んだ時点のファイルをブラウザが抱えています。保存しただけでは、ブラウザは知りません。

必ず、この順でやります。

  1. chrome://extensions を開く
  2. その拡張のカードにある 🔄(更新)ボタンを押す
  3. そのあとで、対象のページをリロードする

2と3の両方が要ります。 これが、拡張開発でいちばん多く繰り返す操作です。

直したもの必要な操作
content.js更新ボタン + ページのリロード
manifest.json更新ボタン(matches を変えたときは、対象ページも開き直す)
バックグラウンド更新ボタン(Service Worker が作り直されます)

この癖がつくまでは、「変わらない=コードが悪い」と思い込みます。 ほとんどの場合、押していないだけです。

権限は、少ないほど強い

ここまでで作った拡張には、permissions が1つもありません。 それでも他人のページを書き換えられています。

では、権限とは何なのか。

chrome://extensions の拡張カードで「詳細」を開くと、「サイトへのアクセス」という欄があります。今の拡張は、そこに obmes.com だけが並んでいるはずです。

[スクリーンショット: 04_権限の表示.png] 拡張の「詳細」を開いて、「サイトへのアクセス」に obmes.com だけが並んでいる状態を撮ってください。

ここで、実験を1つします。manifest.json の matches を、こう書き換えてみてください。

"matches": ["<all_urls>"]

更新ボタンを押して、もう一度「詳細」を見ます。表示がこう変わります。

サイトへのアクセス: すべてのサイト
この拡張機能は、アクセスしたウェブサイト上のデータの読み取りと変更ができます

この2行目が、権限画面の正体です。

ストアで拡張を入れようとしたとき、この文が出て一瞬ためらった経験があるはずです。作る側から見ると、あれは脅し文句ではなく、事実そのものです。

<all_urls> を付けた拡張に出来ることを、正確に並べます。

  • 開いたすべてのページの本文を読める(会社のグループウェア、社内Wiki、管理画面を含む)
  • 入力欄の中身を読める。 次の1行で終わりです
document.querySelectorAll('input').forEach((el) => console.log(el.value));
  • type="password" も、この input に含まれます
  • ページを書き換えられる。 振込先の口座番号を、見た目だけ差し替えることも出来ます
  • ログイン済みの状態で、そのページから通信できる

この記事で、これ以上のコードは書きません。 書ける必要が無いからです。「1行で出来る」ことが分かれば、目的は達しています。

元に戻してください。 matches を ["https://obmes.com/*"] に戻して、更新ボタンを押します。

だから、こう決めます

原則具体的に
matches は最小に動かしたいサイトだけを列挙する。「あとで広げるかも」で <all_urls> を書かない
permissions は要ってから足す通信するまで host_permissions は要りません。タブを触るまで tabs は要りません
optional_permissions を検討する使う瞬間に利用者へ聞く形にも出来ます。入れる時点で全部要求する必要はない
消し忘れない試しに足した権限は、動いたあとで必ず外して読み込み直す

権限は「機能」ではなく「利用者へのお願い」です。少ないほど、入れてもらいやすくなります。

自分だけが使う拡張でも、この癖をつけます。 バグで暴走したときの被害範囲が、そのまま matches の広さだからです。

バックグラウンド(Service Worker)

ここは PWAの回の回収です。あの回で書いた Service Worker が、まったく同じ制約ごと、拡張でも出てきます。

manifest.json に1行足します。

"background": {
  "service_worker": "background.js"
}

background.js を作ります。

chrome.runtime.onInstalled.addListener(() => {
  console.log('読了時間バッジ: インストールまたは更新されました');
});

chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  console.log('ページから届きました:', message);
  sendResponse({ ok: true });
});

更新ボタンを押すと、カードに 「Service Worker」というリンクが出ます。押すと、そのバックグラウンド専用の開発者ツールが開きます。

console.log の出る場所が、コンテンツスクリプトとは別です。

どこで動くかログの出る場所
コンテンツスクリプトそのページで F12 → Console
バックグラウンド拡張カードの「Service Worker」リンク

この2つを混同して「ログが出ない」と悩むのが、2つ目の定番です。

常駐しません

MV3 のバックグラウンドは、ずっと動きません。 ここが V2 との一番大きな違いで、古い記事が使えなくなる理由です。

  • 用が無くなると、数十秒で止まります。 カードの表示が「Service Worker(非アクティブ)」に変わります
  • 止まると、グローバル変数の中身は消えます。 次に呼ばれたときはまっさらからです
  • イベントが来ると、また起き上がります

つまり、こう書いてはいけません。

let count = 0;  // ❌ 止まった瞬間に 0 に戻る

状態は、必ず外に置きます。 その置き場所が、次の chrome.storage です。

バックグラウンドは「住んでいる」のではなく、「呼ばれたら来る」。 PWAの回とまったく同じ考え方です。

[スクリーンショット: 05_service_worker非アクティブ.png] しばらく放置して、拡張カードの表示が「Service Worker(非アクティブ)」に変わったところを撮ってください。

設定を保存する(chrome.storage)

「1分あたり500文字」を決め打ちにしましたが、人によって読む速さは違います。 ここを保存できるようにします。

manifest.json に権限を足します。これは本当に必要な権限です。

"permissions": ["storage"]

content.js の最後の3行を、こう変えます。

chrome.storage.sync.get({ charsPerMinute: 500 }, (settings) => {
  const chars = countCharacters();
  const minutes = Math.max(1, Math.round(chars / settings.charsPerMinute));
  showBadge(minutes, chars);
});

値を変えたいときは、拡張カードの「Service Worker」リンクから開いた開発者ツールのコンソールでこう打ちます(ページの Console で打つ場合は、上部の「top」を拡張機能の名前に切り替えてから。ページ側の実行環境には chrome.storage がありません)。

chrome.storage.sync.set({ charsPerMinute: 700 });

ページをリロードすると、数字が変わります。 そしてブラウザを再起動しても、700 のままです。

localStorage と、どう違うのか

「保存できるならどっちでもいい」ではありません。 ここは、拡張を書くうえで一番間違えやすい分岐です。

localStoragechrome.storage
誰の持ち物か開いているサイトの持ち物✅ 拡張の持ち物
コンテンツスクリプトから使うと他人のサイトの領域に書き込む拡張の領域に書き込む
読み書き同期(その場で返る)非同期(コールバックか await)
Service Worker から❌ 使えない✅ 使える
端末をまたぐしないchrome.storage.sync なら同期される
サイト側から見えるか見える。消される見えない

一番の理由は、1行目です。 コンテンツスクリプトの中で localStorage.setItem(...) と書くと、それは「他人のサイトの localStorage」に書き込まれます。

  • 相手のサイトのデータを汚します(キー名がぶつかれば、相手のサイトが壊れます)
  • 相手のサイトの JavaScript から、中身が読めます
  • 利用者がそのサイトのデータを消したら、こちらの設定も消えます
  • サイトごとに別々なので、「拡張の設定」として1つにまとまりません

そして4行目。バックグラウンドは Service Worker なので localStorage を触れません。 これも PWAの回と同じ制約です。chrome.storage なら、コンテンツスクリプトからもバックグラウンドからも、同じものが読めます。

拡張の中では localStorage を使わない。 これは覚えておいて損の無い、数少ない断定です。

非同期になるのは面倒に見えますが、非同期処理の回の await がそのまま使えます。

const settings = await chrome.storage.sync.get({ charsPerMinute: 500 });

他人のページを触るときの作法

ここからは、動かすためではなく、壊さないための話です。自分のページではないので、前提が変わります。

1. 既存の CSS を巻き込まない

やってはいけないのがこれです。

document.querySelectorAll('div').forEach((el) => {
  el.style.border = '1px solid red';  // ❌ 相手のページが崩壊する
});

極端な例に見えますが、.badge や .title のような「よくあるクラス名」を自分の CSS で定義すると、実質同じことが起きます。相手のページにも .badge があれば、巻き添えで見た目が変わります。

CSSの回でやったとおり、CSS はページ全体で1つの空間を共有します。 拡張が足したスタイルも、その空間に入ります。

対策は2つです。

方法やり方評価
Shadow DOMattachShadow() の中に閉じ込める。中の CSS は外に出ず、外の CSS も入らない✅ 今回採用したもの
id 付きの限定セレクタ#reading-time-badge-host .badge { ... } のように、自分の id から必ず書き出す○ 手軽。ただし書き忘れると漏れる

content.js で attachShadow({ mode: 'open' }) を使ったのは、これが理由でした。あの中に書いた .badge は、相手のページのどの .badge にも影響しませんし、影響も受けません。

逆向きの被害も防げます。 相手のページに div { display: none !important } のような強い指定があっても、Shadow DOM の中までは届きません。「なぜか自分の要素が消える」を根本から避けられます。

2. 読み込みが終わる前に触らない

run_at の話です。document_start にすると document.body が null の瞬間があります。 DOM操作の回の Cannot read properties of null が、他人のページで再現します。

迷ったら document_idle。 今回もそうしました。

もう1つ、SPAという落とし穴があります。ルーティングの回でやったとおり、React などで作られたサイトは、画面が変わってもページは再読み込みされません。 つまりコンテンツスクリプトは1回しか動きません。

「最初の画面では出るのに、リンクを踏むと消える」——これはバグではなく、そもそも再実行されていないだけです。対処は MutationObserver で DOM の変化を見張ることですが、今回はやりません。 覚えておく程度で十分です。

3. 二重に足さない

showBadge() の最初の1行が、これでした。

if (document.getElementById(HOST_ID)) return;

すでに自分の要素があるなら、何もしない。 これが無いと、更新ボタンを押すたびにバッジが増えていきます。id を付けておく一番の理由は、この判定のためです。

4. innerHTML を使わない

DOM操作の回で「危険」と書いたものです。拡張ではさらに危険度が上がります。

相手のページから読み取った文字を innerHTML に入れると、相手のページの内容が、こちらの権限で実行されます。 今回のコードで textContent しか使っていないのは、そのためです。

そもそも、MV3 では拡張ページの innerHTML によるスクリプト実行はブロックされます。 CSPの回でやった Content-Security-Policy が、拡張には最初から強制で掛かっているからです。

5. 元に戻せるようにしておく

足した要素には必ず id を付け、あとから消せるようにします。 バッジを消したくなったら、コンソールでこれだけです。

document.getElementById('reading-time-badge-host').remove();

足すことより、引くことのほうが後で効きます。

危ないこと

ここが、この記事で一番読んでほしい節です。作れるようになった直後に読む価値があります。

1. 入力欄の中身は、読めます

さっきの1行です。拡張が入っているだけで、そのページのパスワード欄も、クレジットカード番号も、検索欄に打った文字も、全部読めます。

そして利用者からは、読んでいるかどうかが分かりません。 見た目は何も変わりません。

拡張を入れるということは、「このコードにすべてのページを見せる」と決めることです。

だから、こう振る舞います。

  • 要らない拡張は消す。 「いつか使うかも」で置いておかない
  • 入れる前に「サイトへのアクセス」を見る。 電卓の拡張が「すべてのサイト」を要求していたら、おかしい
  • 拡張の数を数える。 20個入っていて全部を説明できないなら、それは既に危険な状態です

2. 自分の拡張に、外部スクリプトを読み込まない

CSPの回の回収です。こう書きたくなる日が来ます。

const s = document.createElement('script');   // ❌
s.src = 'https://cdn.example.com/library.js';
document.head.appendChild(s);

MV3 では、これが仕様として禁止されています。 「行儀が悪い」ではなく、ストアの審査で落ちますし、拡張のページでは実行そのものがブロックされます。

理由は、CSPの回で書いたことと同じです。

外から取ってくるスクリプトは、「今日と同じ中身が明日も来る」保証がありません。

しかも拡張の場合、そのスクリプトは拡張の権限で動きます。 つまり <all_urls> を持った拡張が外部スクリプトを読み込むと、CDN の中身を差し替えられた瞬間、利用者の全ページが持っていかれます。

使いたいライブラリは、ファイルをフォルダの中に置きます。 拡張は zip で配る仕組みなので、最初から全部同梱する前提で出来ています。

3. 拡張は、売られます

これが一番、身に覚えの無い事故です。 型はいつも同じです。

  1. 誰かが便利な拡張を作る。中身はきれい。何十万人が入れる
  2. 何年か経ち、作者が飽きる。「買い取りたい」というメールが来る
  3. 売る。拡張のIDは変わりません。ストアのページも同じ
  4. 新しい所有者が更新を出す。中身に、閲覧履歴の送信や、リンクの差し替えが入る
  5. 拡張は自動で更新されます。 利用者は何も押していないのに、新しい中身に入れ替わります

インストールしたときのコードと、いま動いているコードは、別物かもしれません。 ここが、普通のアプリと違って気持ちの悪いところです。

確実な対策はありません。 出来ることは、この3つくらいです。

  • 数を減らす(これが一番効きます)
  • たまに chrome://extensions を開いて棚卸しする。 名前を見て思い出せないものは消す
  • 自分で作れるものは、自分で作る。 今回のバッジは30行でした。「これくらいなら自分で書ける」の範囲が広がると、入れる拡張が減ります

この記事の本当の狙いは、そこです。

Firefox との違い

ほぼ同じ manifest.json で動きます。 WebExtensions という共通の仕様があるからで、今回のバッジ程度なら、そのまま読み込めます。 ただし細部が違い、実務ではそこで時間を取られます。名前空間が chrome. ではなく browser. で(chrome. も動きますが)、Firefox の API は Promise を返すため await がそのまま書けます。バックグラウンドは Service Worker ではなく background.scripts の形も使えて、MV3 の「止まる」制約が Chrome ほど強くありません。 読み込み方も違い、about:debugging の「一時的なアドオン」から入れますが、ブラウザを閉じると消えます。 そして継続して使うには Mozilla の署名が要ります。「両対応」を目指すのは、片方が動いてからで十分です。

配り方は、3段階ある

作った拡張を人に渡す方法は3つあり、手間と責任が段違いです。

方法手順向いている相手今回
① 手元で読み込むフォルダを「パッケージ化されていない拡張機能を読み込む」で入れる自分だけ✅ これで終わり
② zip を渡すフォルダを zip で固めて渡す。相手も開発者モードで展開して読み込む家族・同僚など数人△ 相手に手順が要る
③ ストアに出す開発者登録(初回に登録料)→ zip をアップロード→審査→公開不特定多数❌ やりません

③をやらない理由を、はっきり書いておきます。

  • お金がかかる(Chrome の開発者登録は初回に一度、有料です)
  • 審査に時間がかかる。 権限が広いほど長くなり、説明を求められます
  • 公開した瞬間、他人のブラウザで動くものの責任を負います。 バグが自分のPCだけで済まなくなります
  • そして、学習としては何も増えません。 拡張の仕組みで学べることは、手元に読み込んだ時点で全部済んでいます

②の zip は、「作品として見せる」用途では有効です。READMEの回で書いたとおり、動く場所があるかどうかで見え方が変わります。 リポジトリに zip を置き、READMEに「開発者モードで読み込む3行」を書いておけば、5分で試してもらえます。

つまずいたところ

実際に詰まった順に並べます。

1. 更新ボタンを押さず、30分

書いたとおりです。 content.js を直しては保存し、リロードしては首をかしげ、コードを疑い、console.log を足し、それも出ない。その console.log も、読み込まれていない古いファイルの話でした。

「変わらないときは、まず更新ボタン」 を体に入れるまでは、必ずやります。

2. Invalid match pattern で読み込めない

最初、matches にこう書きました。

"matches": ["obmes.com"]

スキームもパスも無いので、2重に不正です。エラーの文言は正確でしたが、「マッチパターン」という言葉が何を指すのか分かっていなかったので、10分ほど読み違えました。

正しくは https://obmes.com/* です。 スキーム・ホスト・パスの3つが揃って初めて形になります。

3. console.log の出る場所を探し回った

バックグラウンドを足した直後、ログがどこにも出ませんでした。 ページの開発者ツールを見ても無い。管理画面にも無い。

答えは、拡張カードの中の「Service Worker」というリンクでした。押すと専用の開発者ツールが開きます。 ここを知らないと、バックグラウンドは一切デバッグできません。

さらに、開いた直後は空です。 バックグラウンドが眠っていることがあるので、更新ボタンを押して起こしてから見ます。

4. バッジが相手のCSSに潰された

最初は Shadow DOM を使わず、普通の div に class="badge" を付けていました。あるサイトで、まったく見えませんでした。

開発者ツールで見ると、要素はちゃんと居ます。相手のページの CSS に .badge があって、そちらの色と position が効いていました。

Shadow DOM に入れ替えたら、一発で直りました。 この経験があるので、他人のページに何かを足すときは、最初から Shadow DOM に入れます。

5. <all_urls> を試して、怖くなった

権限の実験のところです。「すべてのサイト」「データの読み取りと変更ができます」 と自分の拡張の詳細画面に出たとき、自分が入れている他の拡張の詳細画面を、全部開きました。

その日、6個消しました。 名前を見て何をするものか思い出せないものが、6個あったからです。

6. 文字数が明らかに多い

最初、document.body.textContent で数えていました。サイドバーもフッターも、CSS で隠された要素も全部入り、記事本文の倍以上になりました。

article を先に探すようにし、innerText に変え、空白を落として、ようやく妥当な数字になりました。「本文だけを取る」は、思っているより難しい仕事です。今回のコードも、完璧ではありません。

後片づけ

必ずやります。 開発者モードで読み込んだ拡張は、ブラウザを閉じても残り続けます。

  1. chrome://extensions を開く
  2. 「読了時間バッジ」のカードの 「削除」 を押す
  3. 確認ダイアログで、もう一度「削除」

これで、他人のページに差し込まれる JavaScript は無くなります。

「デベロッパー モード」もオフに戻しておきます。 オンのままだと、Chrome を起動するたびに「デベロッパー モードの拡張機能を無効にしてください」という警告が出続けます。

フォルダは消しても、残しても構いません。 消すときは Windows の PowerShell で。

PowerShell
PS> Remove-Item -Recurse -Force "$HOME\Desktop\reading-time-badge"

chrome.storage に保存した値は、拡張を削除した時点で一緒に消えます。 別途消す作業は要りません。

そして、ついでにやってほしいこと。

いま入っている拡張を、上から順に「詳細」を開いて、「サイトへのアクセス」を全部見てください。

これが、この記事の一番の実用的な成果かもしれません。

まとめ — 理解できたこと

拡張は、新しい技術ではありませんでした。

  • 書いたのは、DOM操作の回と同じ JavaScriptでした。querySelector と createElement と textContent だけです。違うのは動く場所だけでした
  • 中身は3つでした。manifest.json が宣言し、コンテンツスクリプトがページを触り、バックグラウンドが裏を回す。 それ以上の部品は、この3つのおまけです
  • matches が、そのまま権限の広さでした。<all_urls> と書けば、パスワード欄まで読める拡張が1行で出来ました。インストール時の権限画面は脅しではなく、書いたことがそのまま出ていただけでした
  • バックグラウンドは常駐しません。 PWAの回でやった Service Worker と、同じ制約でした。だから状態は chrome.storage に置きます
  • localStorage は使いません。 コンテンツスクリプトから書くと、他人のサイトの領域を汚すからです
  • 他人のページを触る作法は、結局「巻き込まない」でした。Shadow DOM で閉じ込め、document_idle を待ち、id で二重実行を止め、innerHTML を使わない
  • 外部スクリプトは読み込みません。 CSPの回で書いた「明日も同じ中身とは限らない」が、拡張では利用者の全ページに波及します

そして、一番大きい収穫は、たぶんこれです。

30行で作れると分かった時点で、入れる拡張が減りました。

便利そうな拡張を見つけたとき、「これ、自分で書けるのでは」と一度考える。 書けるなら書く。書けないなら、権限の欄を見てから決める。 ——作れるようになるというのは、そういうことでした。

参考リンク


次に読む

この記事は 【第9段階】作品を1つ完成させる の 7 / 10 本目です。

記事
← 前の記事npm publish は取り消せない — CLIツールを配る
→ 次の記事Webhookは向こうから来る — Botと署名検証

上から順に読めば積み上がるように並べています。 飛ばしても構いませんが、詰まったら前の回に戻ってください。

全体の順路は はじめに にあります。

roadmap.sh のどこをやっているか

作品づくり。ブラウザ拡張は roadmap.sh の範囲外。

よかったらシェアしてね!
  • URLをコピーしました!
  • URLをコピーしました!

コメント

コメントする

目次