優化首圖體驗的終極指南：SVG + BlurHash + LQIP 實戰解密

// Node.js 環境中使用 blurhash 套件
import { encode } from "blurhash";
import sharp from "sharp";

async function generateBlurhash(imagePath) {
  // 讀取圖片
  const { data, info } = await sharp(imagePath)
    .raw()
    .ensureAlpha()
    .toBuffer({ resolveWithObject: true });

  // 生成 BlurHash
  const hash = encode(
    new Uint8ClampedArray(data),
    info.width,
    info.height,
    4, // x 組件數
    3 // y 組件數
  );

  return {
    blurhash: hash,
    width: info.width,
    height: info.height,
  };
}

// 使用方式
const metadata = await generateBlurhash("path/to/image.jpg");
// { blurhash: "LlNA}44TN{kqyEtls:xux^tRRjRi", width: 800, height: 600 }

<template>
  <div
    class="progressive-image"
    :style="{ paddingBottom: `${(height / width) * 100}%` }"
  >
    <!-- SVG 容器，確保比例一致 -->
    <svg
      v-if="!loadedLqip && !loadedHighQuality"
      viewBox="0 0 width height"
      preserveAspectRatio="none"
      :width="width"
      :height="height"
    ></svg>

    <!-- BlurHash 預覽 (通過 Canvas 渲染) -->
    <canvas
      v-if="useBlurHash && blurHash && !loadedHighQuality"
      ref="blurHashCanvas"
      class="blur-preview"
      :class="{ 'fade-out': loadedHighQuality }"
    ></canvas>

    <!-- LQIP 預覽 -->
    <img
      v-if="lqipSrc && !useBlurHash && !loadedHighQuality"
      :src="lqipSrc"
      class="lqip-preview"
      :class="{ 'fade-out': loadedHighQuality }"
      alt=""
      @load="loadedLqip = true"
    />

    <!-- 高品質圖片 -->
    <img
      ref="highQualityImg"
      :data-src="src"
      :alt="alt"
      class="high-quality"
      :class="{ loaded: loadedHighQuality }"
      @load="onHighQualityLoaded"
    />
  </div>
</template>

<script setup>
import { ref, onMounted, watch } from "vue";
import { decode } from "blurhash";

const props = defineProps({
  src: { type: String, required: true },
  alt: { type: String, default: "" },
  width: { type: Number, required: true },
  height: { type: Number, required: true },
  lqipSrc: { type: String, default: "" }, // Base64 LQIP
  blurHash: { type: String, default: "" }, // BlurHash 字串
  useBlurHash: { type: Boolean, default: false }, // 是否使用 BlurHash
});

const loadedLqip = ref(false);
const loadedHighQuality = ref(false);
const blurHashCanvas = ref(null);
const highQualityImg = ref(null);
const observer = ref(null);

// 渲染 BlurHash 至 Canvas
const renderBlurHash = () => {
  if (!props.blurHash || !blurHashCanvas.value) return;

  const canvas = blurHashCanvas.value;
  const ctx = canvas.getContext("2d");
  const canvasWidth = 32; // 低解析度即可
  const canvasHeight = Math.floor(canvasWidth * (props.height / props.width));

  canvas.width = canvasWidth;
  canvas.height = canvasHeight;

  // 解碼 BlurHash 字串為像素資料
  const pixels = decode(props.blurHash, canvasWidth, canvasHeight);
  const imageData = new ImageData(pixels, canvasWidth, canvasHeight);
  ctx.putImageData(imageData, 0, 0);
};

// 監聽圖片進入視口
const setupIntersectionObserver = () => {
  if (!highQualityImg.value) return;

  observer.value = new IntersectionObserver(
    (entries) => {
      const entry = entries[0];
      if (entry.isIntersecting) {
        // 圖片進入視口，開始載入高品質圖片
        highQualityImg.value.src = highQualityImg.value.dataset.src;
        observer.value.disconnect();
      }
    },
    { rootMargin: "200px" }
  ); // 預載邊界

  observer.value.observe(highQualityImg.value);
};

const onHighQualityLoaded = () => {
  loadedHighQuality.value = true;
};

onMounted(() => {
  if (props.useBlurHash) {
    renderBlurHash();
  }
  setupIntersectionObserver();
});

// 當 BlurHash 或 Canvas 引用變化時重新渲染
watch(() => [props.blurHash, blurHashCanvas.value], renderBlurHash);
</script>

<style scoped>
.progressive-image {
  position: relative;
  width: 100%;
  overflow: hidden;
  background-color: #f0f0f0;
}

.blur-preview,
.lqip-preview,
.high-quality {
  position: absolute;
  top: 0;
  left: 0;
  width: 100%;
  height: 100%;
  transition: opacity 0.5s ease;
}

.blur-preview {
  filter: blur(20px);
  transform: scale(1.1); /* 彌補模糊邊緣 */
}

.lqip-preview {
  object-fit: cover;
  filter: blur(10px);
  transform: scale(1.05);
}

.high-quality {
  opacity: 0;
  object-fit: contain;
}

.high-quality.loaded {
  opacity: 1;
}

.fade-out {
  opacity: 0;
}
</style>

---
// ProgressiveImage.astro
import { Image } from 'astro:assets';
import ProgressiveImageVue from './ProgressiveImage.vue';
import { getImageAsBuffer } from '../utils/image';

const { src, alt, width, height, blurhash } = Astro.props;

// 動態導入圖片
let imageData;
if (typeof src === 'string') {
  // 遠程圖片，使用提供的 blurhash
  imageData = {
    src,
    blurhash,
    width,
    height,
    useBlurHash: true
  };
} else {
  // 本地圖片，可以使用 LQIP 或 BlurHash
  try {
    // 如果使用 vite-plugin-lqip
    const lqipData = await import(`${src.src}?lqip`);
    imageData = {
      src: src.src,
      lqipSrc: lqipData.default.lqip,
      width: lqipData.default.width,
      height: lqipData.default.height
    };
  } catch (e) {
    // 回退至標準圖片
    imageData = {
      src: src.src,
      width: width || src.width,
      height: height || src.height
    };
  }
}
---

<ProgressiveImageVue
  client:load
  src={imageData.src}
  lqipSrc={imageData.lqipSrc}
  blurHash={imageData.blurhash}
  useBlurHash={imageData.useBlurHash}
  width={imageData.width}
  height={imageData.height}
  alt={alt}
/>