PNG s průhledností se při tvorbě variant převede na JPEG a logo má černé pozadí
import { Aside } from ‘@astrojs/starlight/components’;
Symptom
Sekce “Symptom”Logo partnera nahrané jako PNG s průhledným pozadím se na webu zobrazilo jako plný černý čtverec. Originál v adminu vypadal správně, chyba byla jen u zmenšených variant (thumb, md, lg), které web používá.
Root cause
Sekce “Root cause”Zpracování médií vytváří zmenšené varianty jednotně:
const out = await sharp(input).resize({ width }).jpeg({ quality: 82 }).toBuffer();JPEG nemá alfa kanál; sharp průhledné pixely zploští na výchozí pozadí (černou). U fotografií to nevadí, u log, ikon a razítek ano.
Fix
Sekce “Fix”Formát varianty se volí podle vstupu:
const meta = await sharp(input).metadata();const keepAlpha = !!meta.hasAlpha;const resized = sharp(input).rotate().resize({ width, withoutEnlargement: true });const out = keepAlpha ? await resized.png({ compressionLevel: 9 }).toBuffer({ resolveWithObject: true }) : await resized.jpeg({ quality: 82, mozjpeg: true }).toBuffer({ resolveWithObject: true });variants[name] = { ..., mime: keepAlpha ? "image/png" : "image/jpeg", ext: keepAlpha ? "png" : "jpg" };Unit test: vygenerovat RGBA PNG s průhledným okrajem, projet pipeline a ověřit, že varianta má hasAlpha === true a rohový pixel alfa 0. Už nahraná média je nutné znovu zpracovat (varianty se při uploadu uloží na disk).
Jak se tomu vyvarovat v jiných systémech
Sekce “Jak se tomu vyvarovat v jiných systémech”- Detection:
grep -rn "\.jpeg(" src/lib/mediabez okolníhohasAlpha; vizuálně – loga na světlém pozadí. - Anti-pattern: jeden výstupní formát pro všechny varianty „protože fotky“.
- Lepší přístup: formát podle vstupu (alfa → PNG/WebP, jinak JPEG), případně
flatten({ background: "#fff" }), když má být výstup záměrně JPEG.
Sister bugs / související
Sekce “Sister bugs / související”- Podobný efekt má
flatten()bez barvy nebo převod na WebP salphaQuality: 0.