在 Astro 博客中实现 LQIP（低质量图片占位符）

import sharp from "sharp";

import { glob } from "glob";

import fs from "fs/promises";

import path from "path";

import chalk from "chalk";

//--------- 配置 ---------

const IMAGE_GLOB = "public/img/**/*.{webp,jpg,jpeg,png}";

const OUTPUT_FILE = "src/assets/lqips.json";

//--------- 类型定义 ---------

interface RgbColor {

  r: number;

  g: number;

  b: number;

}

type LqipMap = Record<string, string>;

//--------- 颜色工具函数 ---------

/**

 * RGB 转十六进制字符串

 */

function rgbToHex(rgb: RgbColor): string {

  const toHex = (n: number) =>

    Math.round(Math.max(0, Math.min(255, n)))

      .toString(16)

      .padStart(2, "0");

  return `#${toHex(rgb.r)}${toHex(rgb.g)}${toHex(rgb.b)}`;

}

//--------- 图片处理 ---------

/**

 * 处理单张图片，生成紧凑的颜色字符串

 */

async function processImage(imagePath: string): Promise<string | null> {

  try {

    // Resize to 2x2 to get 4 quadrant colors

    const resized = await sharp(imagePath)

      .resize(2, 2, { fit: "fill" })

      .raw()

      .toBuffer({ resolveWithObject: true });

    const channels = resized.info.channels;

    const data = resized.data;

    // Extract 4 colors (top-left, top-right, bottom-left, bottom-right)

    const colors: string[] = [];

    for (let i = 0; i < 4; i++) {

      const offset = i * channels;

      const rgb: RgbColor = {

        r: data[offset],

        g: data[offset + 1],

        b: data[offset + 2],

      };

      colors.push(rgbToHex(rgb));

    }

    // 紧凑存储：3 个颜色（左上、右上、右下），去掉 # 前缀

    // 用于生成 135deg 斜向渐变

    const compact = `${colors[0].slice(1)}${colors[1].slice(

      1

    )}${colors[3].slice(1)}`;

    return compact;

  } catch (error) {

    console.error(chalk.red(`  Error processing ${imagePath}:`), error);

    return null;

  }

}

/**

 * 文件路径转短键名

 */

function filePathToKey(filePath: string): string {

  // public/img/cover/1.webp → cover/1.webp

  return filePath.replace(/^public\/img\//, "");

}

//--------- 主函数 ---------

async function main() {

  const startTime = Date.now();

  console.log(chalk.cyan("=== LQIP Generator ===\n"));

  const files = await glob(IMAGE_GLOB);

  if (!files.length) {

    console.log(chalk.yellow("No image files found."));

    return;

  }

  console.log(chalk.blue(`Found ${files.length} images\n`));

  const lqips: LqipMap = {};

  let processed = 0;

  for (const file of files) {

    process.stdout.write(`\r  Processing ${processed + 1}/${files.length}...`);

    const compact = await processImage(file);

    if (compact !== null) {

      const key = filePathToKey(file);

      lqips[key] = compact;

      processed++;

    }

  }

  const dir = path.dirname(OUTPUT_FILE);

  await fs.mkdir(dir, { recursive: true });

  await fs.writeFile(OUTPUT_FILE, JSON.stringify(lqips, null, 2) + "\n");

  const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);

  console.log(

    chalk.green(

      `\n\nDone! Generated LQIP for ${processed} images in ${elapsed}s`

    )

  );

  console.log(chalk.cyan(`Output saved to: ${OUTPUT_FILE}`));

}

main();

// 导入构建时生成的 LQIP 数据

let lqips: Record<string, string> = {};

try {

  const lqipData = await import("@assets/lqips.json");

  lqips = lqipData.default as Record<string, string>;

} catch {

  // 文件不存在时静默失败（首次构建前）

}

/**

 * 图片路径转 LQIP 键名

 */

function imagePathToKey(imagePath: string): string {

  return imagePath.replace(/^\/img\//, "");

}

/**

 * 获取图片的 LQIP 渐变 CSS

 */

export function getLqipGradient(imagePath: string): string | undefined {

  const key = imagePathToKey(imagePath);

  const compact = lqips[key];

  if (compact?.length !== 18) return undefined;

  // 解码紧凑格式：18 字符 → 3 个十六进制颜色

  const c1 = `#${compact.slice(0, 6)}`;

  const c2 = `#${compact.slice(6, 12)}`;

  const c3 = `#${compact.slice(12, 18)}`;

  return `linear-gradient(135deg, ${c1} 0%, ${c2} 50%, ${c3} 100%)`;

}

/**

 * 判断是否为外部图片

 */

export function isExternalImage(imagePath: string): boolean {

  return imagePath.startsWith("http://") || imagePath.startsWith("https://");

}

/**

 * 获取 LQIP 内联样式

 */

export function getLqipStyle(imagePath: string): string | undefined {

  if (isExternalImage(imagePath)) {

    return undefined;

  }

  const gradient = getLqipGradient(imagePath);

  return gradient ? `background-image:${gradient}` : undefined;

}

/**

 * 获取 LQIP props（用于组件）

 */

export function getLqipProps(imagePath: string): {

  style?: string;

  class?: string;

} {

  if (isExternalImage(imagePath)) {

    return { class: "lqip-fallback" };

  }

  const style = getLqipStyle(imagePath);

  return style ? { style } : {};

}