image-compression

プラットフォームに関する注意事項

• オプションのヘルパープラグインは一部の環境で役立つ場合がありますが、このスキルに必須のものとして扱ってはなりません。

画像圧縮

謝辞: Peter Bamuhigire、techguypeter.com、+256 784 464178 氏による共有。

使用する場合

• Squoosh と Canvas フォールバックを使用したアップロード前のクライアントサイド画像圧縮、およびサーバーサイドの Sharp による検証。最大幅 1920px、最大サイズ 512KB、透過的な UX、一貫した圧縮統計を必要とする Web アプリに使用します。

生成されるエビデンス

カテゴリ	成果物	形式	例
パフォーマンス	画像圧縮ポリシー	Squoosh のクライアントサイド目標、Canvas フォールバック、Sharp のサーバーサイド検証予算を網羅した Markdown ドキュメント	docs/images/compression-policy.md

参考資料

• 以下のコアワークフローを読んだ後、詳細については references/ ディレクトリを使用してください。

ハイブリッドな画像圧縮パスを使用します:

• クライアントの主力: Squoosh (WASM)
• クライアントのフォールバック: Canvas API
• サーバーのセーフティネット: Sharp

一般的なデフォルト: 長辺 1920 px のエンベロープ、正規出力の最大 512 KB、品質 75 (明示的な品質下限の範囲内で下方に調整)。レンダリングコンテキスト、透過性、または小規模な可読性が それを必要とする場合、プロダクトプロファイルがこれらの値を上書きします。

使用する場合

✅ ユーザー画像をアップロードし、帯域幅を削減する必要がある Web アプリ ✅ 透過的な UX が必要 (ユーザーの操作なし) ✅ モダンなコーデックを望むが、古いブラウザもサポートする必要がある

使用しない場合

❌ サーバーのみのバッチパイプライン (Sharp を直接使用) ❌ 複雑な変換を伴う大規模メディア処理 (ImageMagick/FFmpeg を使用)

コアルール

1. アスペクト比を維持し、拡大は決して行わない。
2. 最大幅 $1920$px、最大サイズ $512$ KB を目標とする。
3. 品質 $75$ から開始し、サイズを満たすために段階的に下げる。
4. 互換性のために JPEG を優先し、サイズが依然として大きすぎる場合は WebP を試す。
5. 圧縮統計 (比率、削減量、処理時間) をログに記録する。
6. クライアントの MIME、拡張子、寸法、圧縮後のバイト数を信頼できないヒントとして扱う。
7. サーバーでは、バイトからコンテンツを検出し、寸法/ピクセル/リソースを制約し、完全にデコードし、 メタデータを削除し、許可リストに登録された正規のラスタ形式に再エンコードする。
8. ロゴ/ファビコンのアルファチャンネルを保持し、透過アートワークを決して JPEG に通さない。
9. 正規出力を公開 Web ルート外の不透明なランダムキーの下に保存し、認可された配信ポリシー を通じてのみ公開する。

判断フロー

1. クライアントでの試行 (Squoosh)
   • リサイズ → 圧縮 → サイズを確認。
   • サイズ制限を満たすまで品質を下げる。
   • それでも大きすぎる場合は、WebP を試す。
2. クライアントのフォールバック (Canvas)
   • リサイズ → toBlob JPEG → 必要に応じて品質を下げる。
3. 権威あるサーバーパイプライン (Sharp、GD、ImageMagick、または同等のもの)
   • デコード前に受信を制限し、バイトから MIME を検出し、デコーダの成功を必須とする。
   • 過剰な幅、高さ、総ピクセル数、フレーム数、メモリ、または処理時間を拒否する。
   • デコード、向きの補正、メタデータの削除、拡大なしのリサイズ、ピクセルからの正規化を行う。
   • 必要な箇所ではアルファを保持し、再エンコード後に最終的な寸法とバイト制限を適用する。
   • 処理が失敗した場合に、元のファイルを保存するフォールバックに決して頼らない。

実装手順 (概要)

1. クライアント圧縮サービス
   • compressImage(file, options) を公開する。
   • 動的インポートで Squoosh を使用する。
   • エラー時は Canvas にフォールバックする。
2. アップロードフック / ハンドラー
   • 入力が画像であることを検証する。
   • 透過的に圧縮する。
   • 圧縮された BLOB をアップロードする。
3. サーバーミドルウェア
   • Sharp を使用して制限を適用する。
   • それでも大きすぎる場合は 413 を返す。
   • 圧縮統計をログに添付する。

必須のデフォルト

• maxWidth: 1920
• maxHeight: 1920
• maxSize: $512 * 1024$
• quality: 75
• minDimensions: 200x200 (サーバーサイド)

アンチパターン

• ❌ サーバー検証のスキップ
• ❌ 失敗時にログを記録せずに元のファイルをアップロードする
• ❌ 画像の拡大
• ❌ ブロッキング UI の使用 (ユーザーに対して透過的でなければならない)

リファレンス (必要に応じて読み込む)

• クライアント実装: references/client.md
• クライアントの使用例: references/client-usage.md
• サーバーミドルウェア + ルート: references/server.md
• ストレージアダプター (S3/ローカル): references/storage.md
• セキュリティチェック: references/security.md
• マネージド SaaS の背景/ロゴ/ファビコンのライフサイクル: saas-managed-visual-assets
• モニタリングと分析: references/monitoring.md
• パフォーマンス目標: references/performance.md
• 品質の例: references/quality-metrics.md
• 環境変数: references/env.md
• Docker (Sharp): references/docker.md
• 実装チェックリスト: references/implementation-checklist.md

出力の期待値

• クライアント側の圧縮は通常 $100$～$500$ ms で完了
• サーバー側の圧縮は通常 $50$～$200$ ms
• 帯域幅の削減 $85$～$97%$

チェックリスト

アンチパターン

• クライアントの出力を信用する。修正: サーバー側でメディアをデコードして検証します。
• file.type、拡張子、またはマジックバイトだけを信頼できる情報として扱う。修正: コンテンツ 検出に加えて、制限付きデコードの成功と正規の再エンコードを必須にします。
• 失敗後に同意なく元のファイルをアップロードする。修正: 復旧可能なエラーを表示し、理由を記録します。
• 小さいソースを拡大する。修正: 元の寸法を維持します。
• 圧縮中にインターフェースをブロックする。修正: 非同期の進捗、キャンセル、再試行を提供します。
• すべてのフォーマットに同じ品質値を適用する。修正: コーデックごとに調整し、代表的な画像を検査します。
• 透過ロゴ/ファビコンを JPEG に変換する。修正: PNG またはアルファ対応の WebP を使用します。
• 永続オブジェクトを元のファイル名から命名する。修正: 不透明なランダムキーを生成し、 元の名前は必要な場合にのみ保護されたメタデータとして保存します。

ケイパビリティ契約

最初にアップロードパスを読み取り、検索します。編集は許可されている場合にのみ行い、サポートされている場合はコーデック、サイズ制限、不正ファイル、サーバー検証のテストを実行します。ネットワークアクセスは依存関係の検証において任意です。

• クライアント: Squoosh を主、Canvas をフォールバックとして使用
• クライアント: サイズ/寸法の制限を適用
• サーバー: 信頼できるコンテンツ検出、制限付きデコード、正規の再エンコード、最終的な制限
• サーバー: ピクセル/フレーム/時間/メモリの予算と、不正/ポリグロットのテストコーパス
• 透過性: ロゴ/ファビコンプロファイルでアルファを保持
• ストレージ: ランダムで不変のキー、プライベートなオリジン、制御された配信、クリーンアップ
• ログ: 圧縮統計と処理時間
• ストレージ: メタデータ付きで画像を保存
• テスト: JPEG/PNG/WebP、大きい画像、モバイル

入力

成果物	必須?	目的
ソース画像、表示サイズ、品質目標、フォーマット、配信の制約	はい	安全な最適化を選択

出力

• 最適化されたアセットと、測定されたサイズ、品質、フォーマット、レンダリングの証拠を生成します。

縮退モード

視覚的な検査やターゲットのレンダリングなしでのフォールバック: 元のファイルを保持し、品質比較を未検証としてマークします。

ワークフロー

使用状況を棚卸しし、フォーマットと寸法を選択し、非破壊的に圧縮し、代表的な状態をレンダリングし、品質とサイズを比較してから、参照を更新します。