jsDelivr と GitHub Pages によるプロジェクト画像の配信
小規模な公開プロジェクトでは、コミットに固定した jsDelivr URL を使って、GitHub にある画像を配信できます。このチュートリアルでは PNG を準備し、生成したファイルを公開します。さらに、必要に応じて GitHub Pages にもコピーを公開し、JavaScript によるフォールバックを追加します。どちらの URL も同じ画像を参照します。
サービスに適したアセットの選択
jsDelivr は CDN サービスであり、インストールする JavaScript ライブラリではありません。GitHub エンドポイントはリポジトリのファイルを直接取得するため、GitHub Pages は前提条件ではありません。Pages と jsDelivr は、ファイルを配信するための別々の手段です。この例では、どちらも PNG のサイズ変更や再圧縮を行いません。
この無料の画像 CDN 構成は、オープンソースの地図デモのスクリーンショットなど、公開プロジェクトに属するアセットに使用してください。jsDelivr の利用ポリシーでは、画像ホスティングサイトへのアップロードの保存を含む、汎用的なファイルやメディアのホスティングを禁止しています。一方、画像アセットを含むアプリやゲームなどの正当なプロジェクトは明示的に認めています。プロジェクトのドキュメントを公開し、適切なライセンスを設定して、配布できる画像だけを公開してください。
GitHub Pages は、GitHub Free の公開リポジトリで利用できます。制限には、公開サイトの容量上限 1 GB と、月間帯域幅のソフトリミット 100 GB が含まれます。また、Pages では、オンラインビジネス、電子商取引サイト、商用 SaaS の運営にサービスを使用することも制限しています。これらのサービスは、非公開のアップロードや汎用的な画像ホスティング事業には適していません。
公開用 PNG の準備
公開プロジェクトをローカルにチェックアウトし、main ブランチで作業を始めます。サンプルリポジトリの名前は map-demo です。URL 内の YOUR-USERNAME と map-demo は、実際のアカウントとリポジトリに置き換えてください。このチュートリアルは、Yarn 4 プロジェクト、Node.js 24 以降、POSIX シェルを使用し、docs/ に既存のサイトがないことを前提としています。ローカルの画像処理ワークフローは、Linux 上の Node.js 26.8.1 と sharp 0.35.4 でテストしています。
画像処理ツール sharpをインストールし、入力用と公開用のディレクトリを作成します。
corepack yarn add --dev --exact sharp@0.35.4 &&
mkdir -p original-images docs/images
8 ビット sRGB の静止 PNG スクリーンショットを original-images/map.png に配置してください。以下の HTML は 640 × 360 ピクセルを想定しています。HTML の寸法と代替テキストを、使用する画像に合わせて変更してください。
次のコードをリポジトリのルートに optimize.cjs として保存します。.png ファイルのうち、original-images/ の直下にあるものを処理し、同じファイル名で新しいバージョンディレクトリに書き込みます。
const fs = require('node:fs/promises')
const path = require('node:path')
const sharp = require('sharp')
async function optimizeImage(inputPath, outputPath) {
const image = sharp(inputPath)
const metadata = await image.metadata()
if (metadata.format !== 'png') throw new Error(`Expected a PNG: ${inputPath}`)
await image.png({ compressionLevel: 9, palette: false }).toFile(outputPath)
}
async function processDirectory(inputDir, outputDir) {
const files = await fs.readdir(inputDir)
// A published version must not be overwritten by a later run.
await fs.mkdir(outputDir)
for (const file of files) {
const inputPath = path.join(inputDir, file)
const stat = await fs.stat(inputPath)
if (!stat.isFile() || !file.endsWith('.png')) continue
await optimizeImage(inputPath, path.join(outputDir, file))
}
}
processDirectory('original-images', 'docs/images/v1').catch((error) => {
console.error(error)
process.exitCode = 1
})
一度実行します。
corepack yarn node optimize.cjs
docs/images/v1/map.png を開き、元の画像と比較してください。スクリプトは画像の寸法を維持し、パレット量子化を行わずに PNG を圧縮します。sharp は通常、sRGB に変換してメタデータを削除します。ファイルが小さくなるとは限らないため、出力を採用する前にサイズを比較してください。PNG の quality を設定するとパレット量子化が有効になり、色が失われる可能性があります。sharp の出力オプションを参照してください。
docs/images/v1 がすでに存在する場合、再実行は失敗し、そのバージョンは変更されません。入力が破損している場合もエラーで終了し、書き込み途中の新しいディレクトリが残ることがあります。そのディレクトリは公開しないでください。入力を修正したら、失敗した未公開の出力ディレクトリだけを削除してから、再試行してください。
生成画像のコミット
docs/images/v1/map.png が Git LFS ポインターではなく、実際の PNG であることを確認してください。jsDelivr が取得できるよう、生成したアセット自体をコミットします。無関係な変更がステージングされていない状態で、リポジトリのルートから実行します。
git add docs/images/v1/map.png &&
git commit -m "Add versioned map screenshot" &&
git push origin main &&
git rev-parse HEAD
最後のコマンドで表示される完全なコミットハッシュを控えておいてください。以下の COMMIT-SHA は、PNG を含むコミットのハッシュを指します。optimize.cjs、package.json、yarn.lock もプロジェクトのソースと一緒に保存してください。node_modules/ はコミットに含めません。
コミットに固定した jsDelivr URL の使用
画像の URL は次のとおりです。
https://cdn.jsdelivr.net/gh/YOUR-USERNAME/map-demo@COMMIT-SHA/docs/images/v1/map.png
プレースホルダーを置き換えてから、ブラウザーで開いてください。生成した PNG が表示されるはずです。jsDelivr のアカウントや Pages へのデプロイは不要です。これは公式に記載されている GitHub URL 形式です。
main、latest、バージョンの省略ではなく、完全なコミットハッシュを使用してください。jsDelivr は静的バージョンとコミット URL を永続的にキャッシュし、有効期間の長いキャッシュヘッダーを付与します。画像を変更したら、新しいコミットで公開して URL を更新してください。GitHub から元の画像を削除しても、キャッシュされたコピーを確実に取り下げられるわけではありません。
任意のフォールバックとして GitHub Pages を追加
jsDelivr URL は、自分のサイトですぐに使用できます。この例にもう一つの配信経路を設けるには、docs/ を Pages で公開します。次のページを docs/index.html として保存してください。
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Map demo</title>
<script src="image.js" defer></script>
</head>
<body>
<h1>Map demo</h1>
<img id="my-image" alt="Screenshot of the map demo" width="640" height="360" />
<noscript>Enable JavaScript to load this image demo.</noscript>
</body>
</html>
信頼性とフォールバック
次のコードを docs/image.js として保存します。YOUR-USERNAME と COMMIT-SHA を置き換えてください。リポジトリ名が異なる場合は、map-demo も置き換えます。前の手順で取得した画像のコミットハッシュを使用してください。ページとスクリプトは後からコミットできます。
function loadImage(imageElement, primarySrc, fallbackSrc) {
imageElement.onerror = function () {
imageElement.onerror = null
console.warn('Primary CDN failed, using fallback')
imageElement.src = fallbackSrc
}
imageElement.src = primarySrc
}
const img = document.getElementById('my-image')
if (!(img instanceof HTMLImageElement)) throw new Error('Missing image element: my-image')
loadImage(
img,
'https://cdn.jsdelivr.net/gh/YOUR-USERNAME/map-demo@COMMIT-SHA/docs/images/v1/map.png',
'https://YOUR-USERNAME.github.io/map-demo/images/v1/map.png',
)
このハンドラーは、画像エラーが発生した場合に一度だけ Pages に切り替えます。両方のオリジンで失敗した場合は、画像の代替テキストを残し、再試行を停止します。待機し続けるリクエストに対するタイムアウトはなく、どちらの経路もソースとして GitHub を共有しています。これは限定的なフォールバックであり、可用性を保証するものではありません。
空の docs/.nojekyll ファイルを作成して
Jekyll 処理を無効にしてから、ページとスクリプトを公開します。
touch docs/.nojekyll &&
git add docs/.nojekyll docs/index.html docs/image.js &&
git commit -m "Add image demo page" &&
git push origin main
リポジトリの Settings で、Pages を開きます。Build and deployment にある
Source を Deploy from a branch に設定し、main と /docs を選択して、Save をクリックします。GitHub の公開ガイドでは、これらの操作項目と、公開に失敗した場合に確認するデプロイの実行について説明しています。ブランチからの公開では GitHub が管理する Actions ワークフローを使用するため、独自の最適化ワークフローは不要です。
デプロイが成功してから https://YOUR-USERNAME.github.io/map-demo/ を開いてください。ここでは、カスタムドメインを使用しない、デフォルトのプロジェクトサイトドメインを想定しています。Pages は docs/ の内容を公開する一方、jsDelivr はリポジトリのルートから読み取るため、パスが異なります。
| 場所 | 画像パス |
|---|---|
| コミット済みファイル | docs/images/v1/map.png |
jsDelivr の @COMMIT-SHA/ に続く部分 | docs/images/v1/map.png |
Pages の /map-demo/ に続く部分 | images/v1/map.png |
更新時は、最適化スクリプトの出力ディレクトリを docs/images/v2 に変更し、新しい画像を生成して確認してからコミットします。スクリプトの CDN URL には、新しいコミットハッシュと v2 パスを使用し、Pages URL には v2 を使用してください。利用側を切り替える前に、新しいアセットをデプロイしてください。古いリンクのために v1 は残しておきます。Pages では URL が Git コミットに固定されません。バージョンディレクトリが安定して同じ内容を返すのは、その内容を変更せずに維持した場合だけです。
構成のテスト
まず、両方の画像 URL を直接開いてください。404 は通常、固定したリビジョンにファイルがコミットされていない、パスや大文字と小文字が異なる、または選択したフォルダーが Pages にまだデプロイされていないことを示します。各レスポンスが HTML エラーページではなく、PNG であることを確認してください。
デモページでブラウザーのネットワーク検証ツールを使い、画像リクエストと画像の寸法を確認してください。jsDelivr の画像 URL を完全一致でブロックして再読み込みすると、Pages へのリクエストは成功するはずです。次に両方の URL をブロックして再読み込みしてください。それぞれに一度ずつリクエストされ、画像の代替テキストが残るはずです。確認後はブロックを解除してください。ページのレスポンスが成功することだけでなく、画像の読み込み動作をテストしてください。
セキュリティ
CORS ヘッダー
通常のクロスオリジンの <img> は、CORS を有効にしなくても表示できます。canvas でそのピクセルを読み取るには、追加の CORS 要件があります。このデモは画像の表示だけを行います。CORS は認証ではなく、公開アセットをダウンロードできる人を制限しません。
直リンクの防止
ページ内の JavaScript では、他者が公開画像 URL を埋め込むことを防げません。非公開画像はこのワークフローに含めないでください。アクセス制御が必要な場合は、認可や署名付き URL を強制できるストレージと配信サービスを使用してください。
複数の画像サイズが必要な場合
この例では、一つの PNG を元の寸法で公開します。srcset や <picture> 要素を追加しても、小さい画像や AVIF/WebP ファイルは生成されません。これらのファイルは、事前に生成してコミットする必要があります。レスポンシブ画像のフォールバックでは、srcset と <source> の失敗した候補もクリアしてから
src を変更する必要があります。そのため、上記の単純なハンドラーは、意図的にこれらの候補を持たない一つの <img> を対象としています。動的なサイズや形式が必要な場合は、Transloadit の画像処理 APIなどの画像変換サービスを検討してください。
