画像配信のキャッシュ設計：Cache-Control / immutable / SWR / ETag（Next.js・CDN・NGINX）

// JavaScript// 1) Next.js 15: next.config.jsで静的画像に長期キャッシュ
/** @type {import('next').NextConfig} */
const nextConfig = {
  async headers() {
    return [
      // public 配下の拡張子（=ビルドでハッシュ付きにしておくこと）
      {
        source: "/:path*\.(?:avif|webp|jpe?g|png|gif|svg)$",
        headers: [
          { key: "Cache-Control", value: "public, max-age=31536000, immutable" },
        ],
      },
      // 可変アップロード（例：/uploads/** は1時間+SWR）
      {
        source: "/uploads/:path*",
        headers: [
          { key: "Cache-Control", value: "public, max-age=3600, stale-while-revalidate=86400" },
        ],
      },
    ];
  },
};
module.exports = nextConfig;

// TypeScript// 2) API Routeで画像を返すときのキャッシュ（s-maxageでCDNにも効かせる）
// app/api/image/[...path]/route.ts
import { NextRequest } from "next/server";

export async function GET(req: NextRequest, { params }: { params: { path: string[] } }) {
  const key = params.path.join("/"); // 例: key = "avatars/u123.webp"
  // 実際はS3/Blob等から取得
  const origin = await fetch("https://img.example.com/" + key, { cache: "no-store" });

  if (!origin.ok) return new Response("Not found", { status: 404 });

  // 元のヘッダを継承しつつ、キャッシュ方針を上書き
  const headers = new Headers(origin.headers);
  headers.set(
    "Cache-Control",
    // ブラウザ: 1分, CDN: 1日, 長時間のSWR: 7日
    "public, max-age=60, s-maxage=86400, stale-while-revalidate=604800"
  );
  // ETag/Last-Modified を残す（条件付きリクエストで304が返せる）
  const etag = headers.get("ETag");
  if (!etag) headers.set("ETag", `W/"${Date.now()}-${key}" `); // 無ければ弱ETagを付与（簡易）

  const buf = await origin.arrayBuffer();
  return new Response(buf, { status: 200, headers });
}

// NGINX# 3) NGINX: 静的(ハッシュ名)は1年+immutable、可変はSWR+ETag
# /etc/nginx/conf.d/site.conf の一例
map $sent_http_etag $cache_control_uploads {
  default "public, max-age=3600, stale-while-revalidate=86400";
}

# 不変資産（/img/** にハッシュ付きで配置）
location ~* \.(?:avif|webp|jpe?g|png|gif|svg)$ {
  add_header Cache-Control "public, max-age=31536000, immutable";
  try_files $uri =404;
}

# 可変アップロード（ETagをon）
location ^~ /uploads/ {
  etag on;
  add_header Cache-Control $cache_control_uploads;
  try_files $uri =404;
}

// Notes# 4) ファイル名にハッシュ（fingerprint）を付けて“安全に長期キャッシュ”
# 例: hero-1600.avif -> hero-1600.2d3af6a.avif
# 生成方法はビルドパイプラインに依存（例：Sharpやローダで contenthash を付与）
# 参照するHTML/JS側は新ハッシュへ書き換わるので、古いキャッシュは自然に切替

// Shell# 5) 検証（ヘッダの確認）
curl -I https://gazou-compressor.jp/img/hero-1600.2d3af6a.avif
curl -I https://gazou-compressor.jp/uploads/user/banner.webp

# 代表的な見え方
# 静的(不変)
# Cache-Control: public, max-age=31536000, immutable
# 可変
# Cache-Control: public, max-age=3600, stale-while-revalidate=86400
# ETag: "686897696a7c876b7e"