ブラウザ拡張は、他人のページを自分の画面で書き換える仕組みです。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つ作り、
manifest.jsonとcontent.jsの2ファイルだけ置く - Chrome の開発者モードで「パッケージ化されていない拡張機能を読み込む」(山場)。読了時間バッジが右上に出るところまで
matchesを書き換えて、動くサイトを絞る。 権限画面がどう変わるかを見る- バックグラウンド(Service Worker)を足して、常駐しないことを目で確かめる
chrome.storageで設定(1分あたりの文字数)を保存する- 拡張を削除して、元に戻す(後片づけ。必ずやります)
先に知る言葉
この記事で初めて出てくる言葉です。 基本的な言葉は用語集にもまとめてあります。
| 言葉 | 意味 |
|---|---|
| 拡張機能(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の中ではありません。
このフォルダの中に、ファイルを2つ作ります。VS 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_version | 3 固定。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_start | HTMLを読む前。DOM はほぼ空 | ページより先に何かを仕込みたいとき(上級) |
document_end | HTMLを読み終えた直後。画像はまだ | 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 の画面です。コマンドは打ちません。
- Chrome のアドレス欄に
chrome://extensionsと入れて開く - 右上の 「デベロッパー モード」をオンにする
- 左上に現れる 「パッケージ化されていない拡張機能を読み込む」 を押す
- さっき作った
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分溶けます。
拡張は、読み込んだ時点のファイルをブラウザが抱えています。保存しただけでは、ブラウザは知りません。
必ず、この順でやります。
chrome://extensionsを開く- その拡張のカードにある 🔄(更新)ボタンを押す
- そのあとで、対象のページをリロードする
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 と、どう違うのか
「保存できるならどっちでもいい」ではありません。 ここは、拡張を書くうえで一番間違えやすい分岐です。
localStorage | chrome.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 DOM | attachShadow() の中に閉じ込める。中の 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. 拡張は、売られます
これが一番、身に覚えの無い事故です。 型はいつも同じです。
- 誰かが便利な拡張を作る。中身はきれい。何十万人が入れる
- 何年か経ち、作者が飽きる。「買い取りたい」というメールが来る
- 売る。拡張のIDは変わりません。ストアのページも同じ
- 新しい所有者が更新を出す。中身に、閲覧履歴の送信や、リンクの差し替えが入る
- 拡張は自動で更新されます。 利用者は何も押していないのに、新しい中身に入れ替わります
インストールしたときのコードと、いま動いているコードは、別物かもしれません。 ここが、普通のアプリと違って気持ちの悪いところです。
確実な対策はありません。 出来ることは、この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 に変え、空白を落として、ようやく妥当な数字になりました。「本文だけを取る」は、思っているより難しい仕事です。今回のコードも、完璧ではありません。
後片づけ
必ずやります。 開発者モードで読み込んだ拡張は、ブラウザを閉じても残り続けます。
chrome://extensionsを開く- 「読了時間バッジ」のカードの 「削除」 を押す
- 確認ダイアログで、もう一度「削除」
これで、他人のページに差し込まれる JavaScript は無くなります。
「デベロッパー モード」もオフに戻しておきます。 オンのままだと、Chrome を起動するたびに「デベロッパー モードの拡張機能を無効にしてください」という警告が出続けます。
フォルダは消しても、残しても構いません。 消すときは Windows の PowerShell で。
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行で作れると分かった時点で、入れる拡張が減りました。
便利そうな拡張を見つけたとき、「これ、自分で書けるのでは」と一度考える。 書けるなら書く。書けないなら、権限の欄を見てから決める。 ——作れるようになるというのは、そういうことでした。
参考リンク
- roadmap.sh — Full Stack Developer
- Chrome for Developers — 拡張機能ドキュメント
- Chrome for Developers — マッチパターン
- Chrome for Developers — 拡張機能の Service Worker
- Chrome for Developers — chrome.storage API
- MDN — ブラウザー拡張機能
- MDN — シャドウ DOM の使用
- MDN — Node.textContent
次に読む
この記事は 【第9段階】作品を1つ完成させる の 7 / 10 本目です。
上から順に読めば積み上がるように並べています。 飛ばしても構いませんが、詰まったら前の回に戻ってください。
全体の順路は はじめに にあります。
roadmap.sh のどこをやっているか
作品づくり。ブラウザ拡張は roadmap.sh の範囲外。

コメント