Astro Image Optimization Guide
Dieser Inhalt ist noch nicht in deiner Sprache verfügbar.
Astro Image Optimization Guide
Section titled “Astro Image Optimization Guide”Overview
Section titled “Overview”This guide explains how to implement image optimization in Astro 7.x with Starlight for blog posts and pages.
Key Concepts
Section titled “Key Concepts”1. Image Location Requirements
Section titled “1. Image Location Requirements”For Astro’s image optimization pipeline to work, images must be stored in the src/ directory, not the public/ directory.
Correct location: src/assets/images/...
Incorrect location: public/assets/images/...
Images in the public/ directory are served as-is and are not optimized by Astro’s image pipeline.
2. File Format Requirements
Section titled “2. File Format Requirements”To use the <Image /> component from astro:assets, the file must be an .mdx file, not a .md file.
.mdfiles are processed as markdown and do not support JSX components like<Image />.mdxfiles support JSX components and can use the<Image />component fromastro:assets
3. The <Image /> Component
Section titled “3. The <Image /> Component”The <Image /> component from astro:assets provides:
- Automatic image optimization (WebP/AVIF formats)
- Responsive image generation with
srcsetattributes - CLS prevention with automatic
widthandheightattributes - Lazy loading support
Implementation
Section titled “Implementation”Step 1: Install Sharp
Section titled “Step 1: Install Sharp”Astro 7.x uses sharp for image optimization. Install it as a dev dependency:
pnpm add -D sharpStep 2: Move Images to src/ Directory
Section titled “Step 2: Move Images to src/ Directory”Move images from public/assets/... to src/assets/images/...:
site/src/assets/images/image-generation/├── 1-nature-landscape.png├── 2-scifi-cyberpunk.png├── 3-portrait-realistic.png├── 4-abstract-artistic.png└── 5-food-culinary.pngStep 3: Create MDX File with <Image /> Component
Section titled “Step 3: Create MDX File with <Image /> Component”Create or convert blog posts to .mdx format:
---title: "Blog Post Title"date: 2026-07-06---
import { Image } from 'astro:assets';import natureImage from '../../../assets/images/image-generation/1-nature-landscape.png';
# Blog Post Content
<Image src={natureImage} alt="Nature Landscape" loading="lazy" />Step 4: Build and Verify
Section titled “Step 4: Build and Verify”Run the build command:
pnpm buildVerify optimized images are generated in dist/_astro/:
dist/_astro/├── 1-nature-landscape.51SGon9e_2putX.webp├── 2-scifi-cyberpunk.JjhCW2vR_Z1taUln.webp├── 3-portrait-realistic.BWz-0tfI_m5CB4.webp├── 4-abstract-artistic.Cgf-1GlJ_1ATgsX.webp└── 5-food-culinary.BWr7H010_Z20apFE.webpCommon Issues
Section titled “Common Issues”Issue 1: Images not optimizing
Section titled “Issue 1: Images not optimizing”Symptom: Images are served as original PNG/JPG files, not WebP/AVIF.
Solution: Ensure images are in src/assets/..., not public/assets/....
Issue 2: <Image /> component not working
Section titled “Issue 2: <Image /> component not working”Symptom: Build fails with “Module not found” or JSX parsing errors.
Solution: Ensure the file is .mdx, not .md. Markdown files do not support JSX components.
Issue 3: Sharp not found
Section titled “Issue 3: Sharp not found”Symptom: Build fails with “MissingSharp: Could not find Sharp.”
Solution: Install sharp as a dev dependency: pnpm add -D sharp
Image Optimization Results
Section titled “Image Optimization Results”Original PNG files (559-677kB) are optimized to WebP format (26-50kB), achieving 85-95% size reduction.
| Original | Optimized WebP | Reduction |
|---|---|---|
| 1-nature-landscape.png (580kB) | 1-nature-landscape.51SGon9e_2putX.webp (34kB) | 94% |
| 2-scifi-cyberpunk.png (631kB) | 2-scifi-cyberpunk.JjhCW2vR_Z1taUln.webp (49kB) | 92% |
| 3-portrait-realistic.png (588kB) | 3-portrait-realistic.BWz-0tfI_m5CB4.webp (26kB) | 96% |
| 4-abstract-artistic.png (677kB) | 4-abstract-artistic.Cgf-1GlJ_1ATgsX.webp (50kB) | 93% |
| 5-food-culinary.png (559kB) | 5-food-culinary.BWr7H010_Z20apFE.webp (30kB) | 95% |