full-page-screenshot

全ページのスクリーンショット

Chrome DevTools Protocol を使用して、任意のウェブページの全ページスクリーンショットを撮影します。スクロールが必要な部分も含め、すべてのコンテンツを収めた単一の PNG を生成します。Node.js 22+ とリモートデバッグを有効にした Chrome 以外の外部依存関係はありません。

前提条件

• Node.js 22+（組み込みの WebSocket を使用）
• リモートデバッグを有効にした Chrome/Chromium

環境の準備状況を確認します。

node "${SKILL_DIR}/scripts/full-page-screenshot.mjs" --check

Chrome の確認に失敗した場合は、ユーザーに chrome://inspect/#remote-debugging を開き、**「このブラウザー インスタンスのリモート デバッグを許可する」**を有効にするよう案内してください。

ワークフロー

オプション A：すでに開いているタブのスクリーンショットを撮影する（認証が必要なページに推奨）

1. 使用可能なタブを一覧表示します。

node "${SKILL_DIR}/scripts/full-page-screenshot.mjs" --list

2. タイトルまたは URL で対象を特定し、撮影します。

node "${SKILL_DIR}/scripts/full-page-screenshot.mjs" <targetId> /tmp/screenshot.png --width 1200 --dpr 1

オプション B：URL のスクリーンショットを撮影する（バックグラウンドタブを開き、撮影後に閉じます）

node "${SKILL_DIR}/scripts/full-page-screenshot.mjs" --url "https://example.com" /tmp/screenshot.png --width 1200 --dpr 1 --wait 15000

注： --url モードではバックグラウンドタブが作成されます。認証が必要なページ（SSO、ログイン画面）が対象の場合は、代わりにオプション A を使用してください。

パラメーター

パラメーター	説明	デフォルト
output	出力 PNG ファイルのパス	/tmp/screenshot.png
--width	CSS ピクセル単位のビューポート幅（記事：1200、ダッシュボード：1440-1920）	1200
--dpr	デバイスピクセル比（2 = Retina、ただしファイルサイズは 4 倍）	1
--wait	ページ読み込みのタイムアウト（ミリ秒、--url モードのみ）	15000
--css	撮影前に適用するカスタム CSS（例：要素を非表示にする）	—

出力の確認

# macOS
sips -g pixelWidth -g pixelHeight /tmp/screenshot.png

# Linux
file /tmp/screenshot.png

主な機能

1. SPA のスクロールコンテナーの拡張 — overflow-y: auto/scroll のコンテナーを検出してスクロールし、遅延読み込みを実行した後、すべてのコンテンツを一度に描画できるよう、Tailwind の h-[calc(...)] を含むオーバーフロー制約を解除します。

2. DOM の安定性検出 — readyState=complete の後、DOM 要素数が安定するまで監視します。これにより、SPA フレームワークによる動的コンテンツの描画が完了します。

3. 遅延読み込みの実行 — ビューポートを段階的にスクロールして IntersectionObserver コールバックを発火させ、その後、すべての <img> 要素の読み込み完了を待ちます。

4. 非常に縦長のページの分割撮影 — 16,000px を超えるページは 8,000px のタイルに分けて撮影し、Python PIL を使用して自動的につなぎ合わせます。PIL が使用できない場合は、タイルを個別に保存します。

5. Chrome の自動検出 — DevToolsActivePort ファイルを読み取ってデバッグポートを特定します。見つからない場合は、ポート 9222、9229、9333 を調べます。

6. CDP プロキシのフォールバック — CDP プロキシがブラウザーの WebSocket を保持している場合、スクリプトはキャプチャにプロキシ API エンドポイント（/eval、/screenshot、/scroll）を使用します。

仕組み

1. Discover Chrome debugging port
2. Connect via WebSocket (CDP)
3. Attach to target / create background tab
4. Set viewport width via Emulation domain
5. Wait: readyState + DOM stability
6. Detect & expand scroll containers
7. Scroll through page (trigger lazy-load)
8. Wait for images to complete
9. Measure final content height
10. Page.captureScreenshot (or tiled capture)
11. Stitch tiles if needed (PIL)
12. Restore viewport, detach, clean up

アンチパターン

しないこと	代わりにすること
高さが 10,000px を超えるページで --dpr 2 を使用する	Chrome のメモリーの問題を避けるため、--dpr 1 を使用する
認証が必要なページや SSO ページで --url を使用する	ユーザーがログイン済みのタブで --list と targetId を使用する
SPA で --wait を 5000 未満に設定する	SPA がデータを取得して描画するには時間が必要です。10000-15000 を使用してください
最初に --check を確認せずに撮影する	Chrome のデバッグが利用可能であることを必ず確認する
すべてのページでビューポート幅を固定する	記事には 1200、ダッシュボードやテーブルには 1440 以上を使用する
出力の確認を省略する	撮影後は必ず sips または file コマンドで確認する

トラブルシューティング

症状	原因	対処方法
"Cannot find Chrome debugging port"	リモートデバッグが有効になっていない	chrome://inspect/#remote-debugging を開いて有効にする
"WebSocket connection timeout"	CDP プロキシが接続を保持している	スクリプトが自動的にプロキシ API にフォールバックする
空白のスクリーンショット	ページがまだ読み込まれていない	--wait の値を増やす
下部が切れている	スクロールコンテナーが拡張されていない	スクリプトが自動的に処理します。問題が続く場合は issue を報告してください
メモリー不足	非常に縦長のページと高い DPR	--dpr を 1 に下げる、または --width を小さくする
"PIL not available for stitching"	Python Pillow がインストールされていない	pip3 install Pillow でインストールするか、タイルを個別のファイルとして保存する

相互参照

• engineering/browser-automation — CDP/Playwright を利用した一般的なブラウザー自動化のパターン
• engineering/performance-profiler — ビジュアルキャプチャを補完する可能性のあるパフォーマンス分析