コンテンツにスキップ

画像

Astroは、プロジェクト内のローカル画像、外部URLの画像、CMSやCDNで管理されている画像など、サイト上で画像を活用するための複数の方法を提供しています。

Astroには、最適化や画像変換を行うための組み込みAstroコンポーネント(<Image />および<Picture />)、Markdownの画像構文(![]())処理、SVGコンポーネント、そして画像生成関数が用意されています。さらに、デフォルトでレスポンシブ画像を自動リサイズするように設定したり、個別の画像やピクチャコンポーネントごとにレスポンシブ属性を指定したりすることもできます。

.astroファイルやMarkdownファイル内では、HTML標準の要素を使った画像やSVGファイルの指定、あるいは各ファイルタイプに応じた標準的な記述方法(MDXやJSXにおける<img />など)も引き続き利用できます。ただし、Astroはこれら画像については処理や最適化を行いません。

また、Astroには動画に関する組み込みのサポートはありません。動画コンテンツの最適化や配信負荷に対応するため、ホスティングされている動画サービス (EN)の利用をおすすめします。

<Image /> (EN)および<Picture /> (EN)コンポーネントの詳細なAPIリファレンスも合わせてご確認ください。

Astroが画像を変換・最適化・バンドルできるように、ローカル画像は可能な限りsrc/配下に保存することをおすすめします。public/ディレクトリ内のファイルは、処理されることなく、常にそのまま配信またはビルドフォルダーにコピーされます。

src/に保存されたローカル画像は、ファイルインポートを行うことで、.astro、.md、.mdx、.mdocおよびその他のUIフレームワークを含むプロジェクト内のすべてのファイルから使用できます。画像はコンテンツと同じフォルダー内など、任意のフォルダーに保存可能です。

処理を一切行いたくない場合は、画像をpublic/フォルダーに保存してください。これらの画像は、自ドメイン上のURLパスとしてプロジェクトファイルから参照でき、パブリックな直リンクを持たせることができます。たとえば、サイトのファビコンは、ブラウザが認識しやすいよう、通常このフォルダーのルート直下に配置されます。

コンテンツ管理システム(CMS) (EN)やデジタルアセット管理(DAM) (EN)プラットフォームなど、画像をリモート環境に保存して利用することもできます。Astroは、API経由でリモートデータを取得したり、完全なURLパスを指定して画像を表示したりすることができます。

外部ソースを扱う際のセキュリティを高めるため、Astroの画像コンポーネントおよびヘルパー関数は、設定ファイルで許可された画像ソースからの画像のみを処理(最適化や変換など)します。許可されていないその他のソースからのリモート画像は、処理を行わずにそのまま表示されます。

オプション: <Image />、<Picture />、<img>、<svg>、SVGコンポーネント

Astroのテンプレート言語では、Astroの<Image/> (EN)コンポーネントを使用して最適化された画像を描画したり、<Picture/> (EN)コンポーネントを使用して複数のサイズやフォーマットを生成したりすることができます。どちらのコンポーネントも、コンテナサイズに基づくリサイズや、デバイスの画面サイズ・解像度に応じたレスポンシブ画像プロパティをサポートしています。

さらに、SVGファイルをAstroコンポーネントとしてインポートして.astroコンポーネント内で使用することもできます。

<img>や<svg>を含むすべてのHTML標準タグも.astroコンポーネント内で利用できます。ただし、HTMLタグで描画された画像は処理(最適化や変換など)が行われず、ビルドフォルダーへそのままコピーされます。

.astroファイル内のすべての画像において、画像タグのsrc属性に指定する値は、画像ファイルの保存場所によって決まります。

  • プロジェクトのsrc/フォルダーにあるローカル画像は、ファイルの相対パスからのインポートを使用します。

    画像およびピクチャコンポーネントでは名前付きインポートを直接指定(例:src={rocket})する一方で、<img>タグではインポートしたオブジェクトのsrcプロパティを指定します(例:src={rocket.src})。

  • リモート画像およびpublic/フォルダーの画像は、URLパスを使用します。

    リモート画像には完全なURL(例:src="https://www.example.com/images/my-remote-image.jpg")を指定し、public/フォルダー内の画像には、その配置場所に対応するサイト内の相対URLパスを指定します(例:public/images/my-public-image.jpgに配置された画像の場合はsrc="/images/my-public-image.jpg")。

src/pages/blog/my-images.astro
---
import { Image } from 'astro:assets';
import localBirdImage from '../../images/subfolder/localBirdImage.png';
---
<Image src={localBirdImage} alt="卵の入った巣の上に座っている鳥" />
<Image src="/images/bird-in-public-folder.jpg" alt="鳥" width="50" height="50" />
<Image src="https://example.com/remote-bird.jpg" alt="鳥" width="50" height="50" />
<img src={localBirdImage.src} alt="卵の入った巣の上に座っている鳥">
<img src="/images/bird-in-public-folder.jpg" alt="鳥">
<img src="https://example.com/remote-bird.jpg" alt="鳥">
<Image /> (EN)および<Picture /> (EN)コンポーネントの必須プロパティやオプショナルプロパティの詳細については、APIリファレンスを参照してください。

オプション: ![]()、<img>(パブリックまたはリモート画像)

.mdファイルでは、標準的なMarkdownの![alt](src)構文を使用します。src/に保存されたローカル画像およびリモート画像は、処理および最適化が行われます。また、レスポンシブ画像をグローバルに設定 (EN)している場合、これらの画像はレスポンシブな動作に対応します。

public/フォルダーに保存された画像は、最適化が行われることはありません。

src/pages/post-1.md
# Markdownページ
<!-- src/assets/ に保存されたローカル画像 -->
<!-- 相対ファイルパスまたはインポートエイリアスを使用してください -->
![満天の星が瞬く夜空](../assets/stars.png)
<!-- public/images/ に保存された画像 -->
<!-- public/ からの相対パスを使用してください -->
![満天の星が瞬く夜空.](/images/stars.png)
<!-- 他のサーバー上のリモート画像 -->
<!-- 画像の完全なURLを使用してください -->
![Astro](https://example.com/images/remote-image.png)

HTMLの<img>タグを使用すると、画像の最適化や処理を行わずに、public/配下の画像や外部の画像を表示することもできます。ただし、<img>タグはsrc/配下のローカル画像には対応していません。

<Image />および<Picture />コンポーネントは、.mdファイルでは使用できません。画像の属性をより細かく制御する必要がある場合は、AstroのMDXインテグレーションを利用して.mdxファイル形式のサポートを追加することをおすすめします。MDXを利用すると、コンポーネントとMarkdown構文を組み合わせるなど、MDXで利用可能な追加の画像オプションを使用できます。

オプション: <Image />、<Picture />、<img />、![]()、SVGコンポーネント

コンポーネントと画像の両方をインポートすることで、.mdxファイル内でAstroの<Image />および<Picture />コンポーネントを使用できます。これらは.astroファイルで使用する場合と同様に記述できます。また、未処理の画像に対してはJSXの<img />タグもサポートされており、HTMLの<img>タグと同じ画像インポートを使用します。

また、インポート不要で記述できる標準的なMarkdownの![alt](src)構文にも対応しています。

src/pages/post-1.mdx
---
title: ページタイトル
---
import { Image } from 'astro:assets';
import rocket from '../assets/rocket.png';
# MDXページ
// 同じフォルダーに保存されているローカル画像
![野生のHouston](houston.png)
// src/assets/ に保存されているローカル画像
<Image src={rocket} alt="宇宙空間のロケット" />
<img src={rocket.src} alt="宇宙空間のロケット" />
![宇宙空間のロケット](../assets/rocket.png)
// public/images/ に保存されている画像
<Image src="/images/stars.png" alt="満天の星空" />
<img src="/images/stars.png" alt="満天の星空" />
![満天の星空](/images/stars.png)
// 別サーバー上のリモート画像
<Image src="https://example.com/images/remote-image.png" />
<img src="https://example.com/images/remote-image.png" />
![Astro](https://example.com/images/remote-image.png)
<Image /> (EN)および<Picture /> (EN)コンポーネントの詳細については、APIリファレンスを参照してください。

UIフレームワークコンポーネント内での画像

Section titled “UIフレームワークコンポーネント内での画像”

画像オプション: フレームワーク固有の画像構文(例: JSXの<img />、Svelteの<img>)

srcなどの画像プロパティにアクセスするには、ローカル画像をあらかじめインポートしておく必要があります。インポートした画像は、各フレームワーク固有の通常の画像構文を使って描画できます。

src/components/ReactImage.jsx
import stars from "../assets/stars.png";
export default function ReactImage() {
return (
<img src={stars.src} alt="満天の星空" />
)
}
src/components/SvelteImage.svelte
<script>
import stars from '../assets/stars.png';
</script>
<img src={stars.src} alt="満天の星空" />

Astroコンポーネント(例: <Image />、<Picture />、SVGコンポーネント)は、UIフレームワークコンポーネント内では使用できません。クライアントアイランドには、そのフレームワーク自体で有効なコードのみを含める必要があるためです。

ただし、.astroファイル内であれば、これらのコンポーネントによって生成された静的コンテンツを子要素として、または名前付き<slot/>を使用してフレームワークコンポーネントに渡すことができます。

src/components/ImageWrapper.astro
---
import ReactComponent from './ReactComponent.jsx';
import { Image } from 'astro:assets';
import stars from '~/stars/docline.png';
---
<ReactComponent>
<Image src={stars} alt="満天の星空" />
</ReactComponent>

Astroには画像用の組み込みコンポーネントとして<Image />と<Picture />の2つが用意されているほか、SVGファイルをインポートしてAstroコンポーネントとして使用することもできます。これらのコンポーネントは、.astroコンポーネントをインポートして描画できるすべてのファイルで使用できます。

以下のような画像の最適化バージョンを表示するには、Astro組み込みの<Image />コンポーネントを使用してください。

<Image />を使用すると、表示する画像を適切にコントロールできるように、ローカル画像や承認済みリモート画像の寸法、ファイル形式、画質を変換できます。この変換処理は、事前レンダリングされるページではビルド時に行われます。ページがオンデマンドでレンダリングされる場合は、ページが表示されるタイミングで動的に変換されます。生成される<img>タグにはalt、loading、decoding属性が含まれ、Cumulative Layout Shift(CLS)を防ぐために画像のサイズ情報が自動で補完されます。

src/components/MyComponent.astro
---
// Imageコンポーネントと画像をインポートします
import { Image } from 'astro:assets';
import myImage from '../assets/my_image.png'; // 1600x900の画像
---
<!-- Imageコンポーネントでは、`alt`属性の指定が必須です -->
<Image src={myImage} alt="画像の説明" />
<!-- 事前レンダリングされた出力 -->
<!-- 画像が最適化され、適切な属性が設定されます -->
<img
src="/_astro/my_image.hash.webp"
width="1600"
height="900"
decoding="async"
loading="lazy"
alt="画像の説明"
/>
<!-- オンデマンドでレンダリングされた出力 -->
<!-- srcには、オンデマンドで生成されたエンドポイントが使用されます -->
<img
src="/_image?href=%2F_astro%2Fmy_image.hash.webp&amp;w=1600&amp;h=900&amp;f=webp"
<!-- ... -->
/>

<Image />コンポーネントは、HTMLの<img>タグで使用できる任意の属性に加えて、複数のコンポーネントプロパティ (EN)を受け入れます。

次の例では、画像コンポーネントにclassを指定しており、これは最終的に生成される<img>要素に適用されます。

src/pages/index.astro
---
import { Image } from 'astro:assets';
import myImage from '../assets/my_image.png';
---
<!-- Imageコンポーネントでは、`alt`属性の指定が必須です -->
<Image src={myImage} alt="" class="my-class" />
<!-- 事前レンダリングされた出力 -->
<img
src="/_astro/my_image.hash.webp"
width="1600"
height="900"
decoding="async"
loading="lazy"
class="my-class"
alt=""
/>

追加: astro@3.3.0

複数の画像形式やサイズを持つ<picture>タグを生成するには、Astro組み込みの<Picture />コンポーネントを使用してください。これにより、優先して表示したいファイル形式を指定しながら、同時にフォールバック用の形式を提供できます。<Image />コンポーネントと同様に、事前レンダリングされるページではビルド時に画像が処理されます。ページがオンデマンドでレンダリングされる場合は、ページが表示されるタイミングで動的に処理されます。

次の例では、<Picture />コンポーネントを使用して、ローカルの.pngファイルをウェブに最適化されたavifおよびwebp形式に変換し、必要に応じて.pngをフォールバックとして表示する<img>を生成しています。

src/pages/index.astro
---
import { Picture } from 'astro:assets';
import myImage from '../assets/my_image.png'; // 1600x900の画像
---
<!-- Pictureコンポーネントでは、`alt`属性の指定が必須です -->
<Picture src={myImage} formats={['avif', 'webp']} alt="画像の説明" />
<!-- 事前レンダリングされた出力 -->
<picture>
<source srcset="/_astro/my_image.hash.avif" type="image/avif" />
<source srcset="/_astro/my_image.hash.webp" type="image/webp" />
<img
src="/_astro/my_image.hash.png"
width="1600"
height="900"
decoding="async"
loading="lazy"
alt="画像の説明"
/>
</picture>
<Picture />コンポーネントのプロパティ (EN)の詳細については、astro:assetsのリファレンスを参照してください。

追加: astro@5.10.0

レスポンシブ画像とは、さまざまなデバイス間でパフォーマンスを向上させるために調整される画像のことです。これらの画像はコンテナに合わせてリサイズでき、訪問者の画面サイズや解像度に応じて異なるサイズで配信できます。

<Image />または<Picture />コンポーネントにlayoutプロパティ (EN)を適用すると、Astroは画像に必要なsrcsetおよびsizesの値を自動的に生成し、画像が適切にリサイズされるように必要なスタイルを適用します。

このレスポンシブの動作がimage.layoutによってグローバルに設定 (EN)されている場合、すべての画像コンポーネントに加え、Markdownの![]()構文を使用するすべてのローカル画像およびリモート画像にも適用されます。

なお、public/フォルダー内の画像は最適化の対象外であり、レスポンシブ画像はサポートされていません。

詳細についてはMDN Web Docsのレスポンシブ画像を参照してください。

レスポンシブ画像用に生成されるHTML出力

Section titled “レスポンシブ画像用に生成されるHTML出力”

デフォルト設定または個別のコンポーネントでlayoutが指定されている場合、画像の寸法とlayoutの種類に基づいて、srcsetおよびsizes属性が自動的に生成されます。constrainedまたはfull-widthレイアウトが適用された画像には、コンテナに合わせてリサイズされるようスタイルが適用されます。

src/components/MyComponent.astro
---
import { Image } from 'astro:assets';
import myImage from '../assets/my_image.png';
---
<Image src={myImage} alt="画像の説明" layout='constrained' width={800} height={600} />

この<Image />コンポーネントは、事前レンダリングされるページで次のようなHTML出力を生成します。

<img
src="/_astro/my_image.hash3.webp"
srcset="/_astro/my_image.hash1.webp 640w,
/_astro/my_image.hash2.webp 750w,
/_astro/my_image.hash3.webp 800w,
/_astro/my_image.hash4.webp 828w,
/_astro/my_image.hash5.webp 1080w,
/_astro/my_image.hash6.webp 1280w,
/_astro/my_image.hash7.webp 1600w"
alt="画像の説明"
sizes="(min-width: 800px) 800px, 100vw"
loading="lazy"
decoding="async"
fetchpriority="auto"
width="800"
height="600"
style="--fit: cover; --pos: center;"
data-astro-image="constrained"
>

image.responsiveStyles: true (EN)を設定すると、画像が正しくリサイズされるように少数のグローバルスタイルが適用されます。追加のスタイルがないと画像がレスポンシブにならないため、ほとんどのケースではこの設定をデフォルトで有効にしておくことを推奨します。

ただし、レスポンシブ画像のスタイル設定をご自身で管理したい場合や、Tailwind 4使用時にこれらのデフォルトスタイルを上書きする必要がある場合は、デフォルト値であるfalseのままにしておいてください。

Astroによって適用されるグローバルスタイルはlayoutの種類によって異なり、生成されたsrcsetおよびsizes属性に対して最良の結果が得られるよう設計されています。デフォルトのスタイルは次のとおりです。

レスポンシブ画像スタイル
:where([data-astro-image]) {
object-fit: var(--fit);
object-position: var(--pos);
}
:where([data-astro-image='full-width']) {
width: 100%;
}
:where([data-astro-image='constrained']) {
max-width: 100%;
}

これらのスタイルは:where()擬似クラスを使用しています。この擬似クラスの詳細度は0であるため、独自のスタイルで簡単に上書きできます。どのようなCSSセレクターであっても:where()より詳細度が高くなるため、対象の画像に対して独自のスタイルを追加するだけで容易に上書きが可能です。

また、<Image />または<Picture />コンポーネントでfitおよびpositionプロパティを設定することで、画像ごとにobject-fitやobject-positionのスタイルを個別に上書きできます。

Tailwind 4におけるレスポンシブ画像

Section titled “Tailwind 4におけるレスポンシブ画像”

Tailwind 4はAstroのデフォルトのレスポンシブスタイルと互換性があります。ただし、Tailwindはカスケードレイヤーを使用しているため、そのルールはAstroのレスポンシブスタイルを含むレイヤーを使用しないルールよりも常に詳細度が低くなります。そのため、AstroのスタイリングがTailwindのスタイリングよりも優先されます。Astroのデフォルトスタイルの代わりにTailwindのルールを適用したい場合は、Astroのデフォルトレスポンシブスタイル (EN)を有効にしないでください。

追加: astro@5.7.0

Astroでは、SVGファイルをインポートしてAstroコンポーネントとして使用できます。Astroは、HTML出力内にSVGのコンテンツをインラインで展開します。

任意のローカル.svgファイルのデフォルトインポートを参照してください。このインポートはAstroコンポーネントとして扱われるため、動的タグを使用する場合と同様の命名規則(大文字で始める、など)に従う必要があります。

src/components/MyAstroComponent.astro
---
import Logo from './path/to/svg/file.svg';
---
<Logo />

<Image />やその他のAstroコンポーネントと同様に、SVGコンポーネントをUIフレームワークコンポーネントの内部で直接使用することはできません。ただし、.astroコンポーネント内であれば、フレームワークコンポーネントに渡すことは可能です。

widthやheight、fill、strokeのほか、ネイティブの<svg>要素で受け入れられる任意の属性をpropsとして渡すことができます。これらの属性は、基礎となる<svg>要素に自動的に適用されます。元の.svgファイルにすでに存在するプロパティに対してコンポーネント経由でpropsを渡した場合は、コンポーネントに渡された値が元の値を上書きします。

src/components/MyAstroComponent.astro
---
import Logo from '../assets/logo.svg';
---
<Logo width={64} height={64} fill="currentColor" />
追加: astro@5.14.0

SvgComponent型を使用することで、.svgアセットに対して型安全性を強制することもできます。

src/components/Logo.astro
---
import type { SvgComponent } from "astro/types";
import HomeIcon from "./Home.svg";
interface Link {
url: string;
text: string;
icon: SvgComponent;
}
const links: Link[] = [
{
url: "/",
text: "ホーム",
icon: HomeIcon,
},
];
---

カスタム画像コンポーネントの作成

Section titled “カスタム画像コンポーネントの作成”

<Image />または<Picture />コンポーネントを別のAstroコンポーネントでラップすることで、再利用可能なカスタム画像コンポーネントを作成できます。これにより、デフォルトの属性やスタイルを一度だけ定義すれば済むようになります。

たとえば、ブログ記事の画像用コンポーネントを作成し、propsとして属性を受け取って各画像に一貫したスタイルを適用できます。

src/components/BlogPostImage.astro
---
import { Image } from "astro:assets";
const { alt, src, ...attrs } = Astro.props;
---
<Image alt={alt} src={src} {...attrs} />
<style>
img {
margin-block: 2.5rem;
border-radius: 0.75rem;
}
</style>

HTMLの<img>タグによる未処理画像の表示

Section titled “HTMLの<img>タグによる未処理画像の表示”

Astroのテンプレート構文では、<img>タグを直接記述することもサポートされており、最終的な出力結果を完全に制御できます。これらの画像は処理や最適化の対象にはなりません。HTMLの<img>タグのすべてのプロパティを受け入れ、必須のプロパティはsrcのみです。ただし、アクセシビリティの観点からaltプロパティを含めることを強く推奨します。

ローカル画像は、対象の.astroファイルからの相対パスでインポートするか、インポートエイリアス (EN)を設定および使用する必要があります。その後、画像のsrcやその他のプロパティにアクセスし、<img>タグで使用できます。

インポートされた画像アセットはImageMetadata型 (EN)に適合し、次のシグネチャを持ちます。

interface ImageMetadata {
src: string;
width: number;
height: number;
format: string;
}

次の例では、Cumulative Layout Shift(CLS)を防ぎCore Web Vitalsを改善するために、画像自体のheightおよびwidthプロパティを使用しています。

src/pages/posts/post-1.astro
---
// ローカル画像をインポート
import myDog from '../../images/pets/local-dog.jpg';
---
// 画像プロパティにアクセス
<img src={myDog.src} width={myDog.width} height={myDog.height} alt="吠えている犬" />

public/内にある画像の場合は、publicフォルダーからの相対ファイルパスをsrcの値として使用します。

<img src="/images/public-cat.jpg" alt="寝ている猫" >

リモート画像の場合は、画像の完全なURLをsrcの値として使用します。

<img src="https://example.com/remote-cat.jpg" alt="寝ている猫" >

<Image />コンポーネントは画像を最適化し、(処理可能な画像について)元の縦横比に基づいてwidthとheightを自動推測することでCLSを防ぎます。可能な限り、.astroファイル内ではこのコンポーネントを使用することが推奨されます。

<Image />コンポーネントを使用できない以下のようなケースではHTMLの<img>要素を使用してください。

  • サポートされていない画像形式を扱う場合
  • Astroによる画像の最適化を行いたくない場合
  • クライアントサイドでsrc属性に動的にアクセス・変更する場合

画像CDNは、すべてのAstro画像オプションと連携して動作します。<Image />コンポーネントや<img>タグのsrc属性、またはMarkdown表記に画像の完全なURLを指定してください。リモート画像で画像最適化を利用する場合は、許可されたドメインまたはURLパターンを設定する必要もあります。

また、CDNによってはAstroプロジェクトへより手軽に統合できるように独自のSDKが提供されている場合もあります。

  • CloudinaryはAstro SDKをサポートしており、CldImageコンポーネントを使って手軽に画像を配置できます。また、Node.js環境で<img>タグに使用するURLを生成できるNode.js SDKも提供されています。
  • ImageKitは画像サービスを登録するAstroインテグレーションを提供しています。これにより、Astro組み込みの<Image />および<Picture />コンポーネントをはじめ、Markdownの![]()やMDXの画像がすべて自動的にImageKitを経由するようになります。既存の画像記述構文を変更することなく、CDN配信、自動AVIF/WebP変換、レスポンシブなsrcset、動的変換などの機能を追加できます。
<Image /> (EN)および<Picture /> (EN)コンポーネントの完全なAPIリファレンスを参照してください。

image.domains (EN)およびimage.remotePatterns (EN)を使用して、画像最適化の対象として承認する画像ソースURLのドメインやパターンのリストを設定できます。この設定は、外部ソースの画像を表示する際にサイトを保護するための追加のセキュリティ層となります。

承認されたソース以外のリモート画像は最適化されませんが、これらの画像に<Image />コンポーネントを使用することで、Cumulative Layout Shift(CLS)を防ぐことができます。

たとえば、次の設定ではastro.buildからのリモート画像のみが最適化を許可されます。

astro.config.mjs
export default defineConfig({
image: {
domains: ["astro.build"],
}
});

次の設定では、HTTPSホストからのリモート画像のみが許可されます。

astro.config.mjs
export default defineConfig({
image: {
remotePatterns: [{ protocol: "https" }],
}
});

コンテンツコレクション内の画像

Section titled “コンテンツコレクション内の画像”

現在のフォルダーからの相対パスを使用することで、ブログ記事のカバー画像など、コンテンツコレクションのエントリに関連付けられた画像をフロントマター内で宣言できます。

src/content/blog/my-post.md
---
title: "初めてのブログポスト"
cover: "./firstpostcover.jpeg" # "src/content/blog/firstpostcover.jpeg"に解決されます
coverAlt: "山々の背後に沈む夕日の写真。"
---
これはブログポストです。

コンテンツコレクションスキーマのimageヘルパーを使用すると、画像の検証とインポートを行えます。

src/content.config.ts
import { defineCollection } from 'astro:content';
import { z } from 'astro/zod';
const blogCollection = defineCollection({
schema: ({ image }) => z.object({
title: z.string(),
cover: image(),
coverAlt: z.string(),
}),
});
export const collections = {
blog: blogCollection,
};

画像はインポートされてメタデータに変換されるため、Astroコンポーネント内で<Image />や<img>、あるいはgetImage()のsrcとして渡すことができるようになります。

以下の例は、先ほどのスキーマに基づいて各ブログ記事のカバー写真とタイトルをレンダリングするブログインデックスページを示しています。

src/pages/blog.astro
---
import { Image } from "astro:assets";
import { getCollection } from "astro:content";
const allBlogPosts = await getCollection("blog");
---
{
allBlogPosts.map((post) => (
<div>
<Image src={post.data.cover} alt={post.data.coverAlt} />
<h2>
<a href={"/blog/" + post.id}>{post.data.title}</a>
</h2>
</div>
))
}

getImage()関数は、APIルートなど、HTML内に直接出力する以外の場所で使用するための画像を生成することを目的としています。<Picture>や<Image>コンポーネントで現在サポートされていないオプションが必要な場合は、getImage()関数を使用して独自のカスタム<Image />コンポーネントを作成できます。

getImage()はサーバー側でのみ使用できます。生成された画像URLをクライアント側(クライアントサイドのスクリプトやフレームワークコンポーネント内など)で使用する必要がある場合は、フロントマター内でgetImage()を呼び出し、結果のsrcをクライアントに渡してください。

src/components/ClientImage.astro
---
import { getImage } from "astro:assets";
import myBackground from "../background.png";
const optimizedBackground = await getImage({ src: myBackground, format: "avif" });
---
<div id="background" data-src={optimizedBackground.src}></div>
<script>
const src = document.getElementById("background")?.dataset.src;
// 必要に応じてクライアント側でsrcを使用してください
</script>
詳細はgetImage()リファレンス (EN)を参照してください。

すべてのユーザーが同じように画像を視認できるわけではないため、画像を使用する際にはアクセシビリティへの配慮が特に重要です。画像にはalt属性を使用して、わかりやすい代替テキストを指定してください。

この属性は、<Image />と<Picture />両方のコンポーネントで必須です。altテキストが指定されていない場合、alt属性を含めることを促すわかりやすいエラーメッセージが表示されます。

画像が単なる装飾目的である場合(ページの理解に寄与しない場合)は、スクリーンリーダーがその画像を無視できるようにalt=""を設定してください。

astro:assetsで使用されるデフォルトの画像サービスはSharpです。image.service (EN)オプションを使用して、画像サービスをさらに設定できます。

使用しているアダプターがAstro組み込みのSharpによる画像最適化をサポートしていない場合(例:Cloudflare)、no-op(何もしない)画像サービスを設定することで<Image />や<Picture />コンポーネントを使用できるように設定できます。これらの環境では、Astroによる画像変換や処理は一切行われないことに注意してください。ただし、Cumulative Layout Shift(CLS)の防止、alt属性の強制、一貫した編集体験など、astro:assetsを使用するその他のメリットは引き続き享受できます。

Sharpによる画像処理を回避するには、passthroughImageService()を設定します。

astro.config.mjs
import { defineConfig, passthroughImageService } from 'astro/config';
export default defineConfig({
image: {
service: passthroughImageService()
}
});

Astroは、ローカル画像と承認されたソースからのリモート画像の両方について、サイトビルド時に処理済み画像アセットをキャッシュディレクトリに保存します。ビルド間でキャッシュディレクトリを保持することにより、処理済みアセットが再利用され、ビルド時間と帯域幅の使用量が改善されます。

デフォルトのキャッシュディレクトリは./node_modules/.astroですが、cacheDir (EN)設定オプションを使用して変更できます。

アセットキャッシュ内のリモート画像はHTTPキャッシュに基づいて管理され、リモートサーバーから返されるCache-Controlヘッダーを尊重します。 画像はCache-Controlヘッダーで許可されている場合にキャッシュされ、新鮮でなくなるまで使用されます。

追加: astro@5.1.0

再検証は、期限切れになったキャッシュ画像が現在も最新であるかどうかをリモートサーバーに問い合わせることで、帯域幅の使用量とビルド時間を削減します。サーバーが画像はまだ新鮮であると応答した場合はキャッシュされたバージョンが再利用され、そうでない場合は画像が再ダウンロードされます。

再検証を行うには、リモートサーバーがレスポンスにLast-ModifiedヘッダーやETag(エンティティタグ)ヘッダーを含めて送信する必要があります。この機能は、If-Modified-SinceおよびIf-None-Matchヘッダーをサポートしているリモートサーバーで利用できます。

コミュニティインテグレーション

Section titled “コミュニティインテグレーション”

Astroプロジェクトで画像を最適化したり操作したりするための、サードパーティ製のコミュニティ画像インテグレーションがいくつか提供されています。

貢献する コミュニティ スポンサー