画像
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リファレンスも合わせてご確認ください。
画像の保存場所
Section titled “画像の保存場所”src/とpublic/の比較
Section titled “src/とpublic/の比較”Astroが画像を変換・最適化・バンドルできるように、ローカル画像は可能な限りsrc/配下に保存することをおすすめします。public/ディレクトリ内のファイルは、処理されることなく、常にそのまま配信またはビルドフォルダーにコピーされます。
src/に保存されたローカル画像は、ファイルインポートを行うことで、.astro、.md、.mdx、.mdocおよびその他のUIフレームワークを含むプロジェクト内のすべてのファイルから使用できます。画像はコンテンツと同じフォルダー内など、任意のフォルダーに保存可能です。
処理を一切行いたくない場合は、画像をpublic/フォルダーに保存してください。これらの画像は、自ドメイン上のURLパスとしてプロジェクトファイルから参照でき、パブリックな直リンクを持たせることができます。たとえば、サイトのファビコンは、ブラウザが認識しやすいよう、通常このフォルダーのルート直下に配置されます。
リモート画像
Section titled “リモート画像”コンテンツ管理システム(CMS) (EN)やデジタルアセット管理(DAM) (EN)プラットフォームなど、画像をリモート環境に保存して利用することもできます。Astroは、API経由でリモートデータを取得したり、完全なURLパスを指定して画像を表示したりすることができます。
外部ソースを扱う際のセキュリティを高めるため、Astroの画像コンポーネントおよびヘルパー関数は、設定ファイルで許可された画像ソースからの画像のみを処理(最適化や変換など)します。許可されていないその他のソースからのリモート画像は、処理を行わずにそのまま表示されます。
.astroファイルにおける画像
Section titled “.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")。
---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リファレンスを参照してください。
Markdownファイル内の画像
Section titled “Markdownファイル内の画像”オプション: ![]()、<img>(パブリックまたはリモート画像)
.mdファイルでは、標準的なMarkdownの構文を使用します。src/に保存されたローカル画像およびリモート画像は、処理および最適化が行われます。また、レスポンシブ画像をグローバルに設定 (EN)している場合、これらの画像はレスポンシブな動作に対応します。
public/フォルダーに保存された画像は、最適化が行われることはありません。
# Markdownページ
<!-- src/assets/ に保存されたローカル画像 --><!-- 相対ファイルパスまたはインポートエイリアスを使用してください -->
<!-- public/images/ に保存された画像 --><!-- public/ からの相対パスを使用してください -->
<!-- 他のサーバー上のリモート画像 --><!-- 画像の完全なURLを使用してください -->HTMLの<img>タグを使用すると、画像の最適化や処理を行わずに、public/配下の画像や外部の画像を表示することもできます。ただし、<img>タグはsrc/配下のローカル画像には対応していません。
<Image />および<Picture />コンポーネントは、.mdファイルでは使用できません。画像の属性をより細かく制御する必要がある場合は、AstroのMDXインテグレーションを利用して.mdxファイル形式のサポートを追加することをおすすめします。MDXを利用すると、コンポーネントとMarkdown構文を組み合わせるなど、MDXで利用可能な追加の画像オプションを使用できます。
MDXファイル内の画像
Section titled “MDXファイル内の画像”オプション: <Image />、<Picture />、<img />、![]()、SVGコンポーネント
コンポーネントと画像の両方をインポートすることで、.mdxファイル内でAstroの<Image />および<Picture />コンポーネントを使用できます。これらは.astroファイルで使用する場合と同様に記述できます。また、未処理の画像に対してはJSXの<img />タグもサポートされており、HTMLの<img>タグと同じ画像インポートを使用します。
また、インポート不要で記述できる標準的なMarkdownの構文にも対応しています。
---title: ページタイトル---import { Image } from 'astro:assets';import rocket from '../assets/rocket.png';
# MDXページ
// 同じフォルダーに保存されているローカル画像
// src/assets/ に保存されているローカル画像<Image src={rocket} alt="宇宙空間のロケット" /><img src={rocket.src} alt="宇宙空間のロケット" />
// public/images/ に保存されている画像<Image src="/images/stars.png" alt="満天の星空" /><img src="/images/stars.png" alt="満天の星空" />
// 別サーバー上のリモート画像<Image src="https://example.com/images/remote-image.png" /><img src="https://example.com/images/remote-image.png" /><Image /> (EN)および<Picture /> (EN)コンポーネントの詳細については、APIリファレンスを参照してください。
UIフレームワークコンポーネント内での画像
Section titled “UIフレームワークコンポーネント内での画像”画像オプション: フレームワーク固有の画像構文(例: JSXの<img />、Svelteの<img>)
srcなどの画像プロパティにアクセスするには、ローカル画像をあらかじめインポートしておく必要があります。インポートした画像は、各フレームワーク固有の通常の画像構文を使って描画できます。
import stars from "../assets/stars.png";
export default function ReactImage() { return ( <img src={stars.src} alt="満天の星空" /> )}<script> import stars from '../assets/stars.png';</script>
<img src={stars.src} alt="満天の星空" />Astroコンポーネント(例: <Image />、<Picture />、SVGコンポーネント)は、UIフレームワークコンポーネント内では使用できません。クライアントアイランドには、そのフレームワーク自体で有効なコードのみを含める必要があるためです。
ただし、.astroファイル内であれば、これらのコンポーネントによって生成された静的コンテンツを子要素として、または名前付き<slot/>を使用してフレームワークコンポーネントに渡すことができます。
---import ReactComponent from './ReactComponent.jsx';import { Image } from 'astro:assets';import stars from '~/stars/docline.png';---
<ReactComponent> <Image src={stars} alt="満天の星空" /></ReactComponent>画像用のAstroコンポーネント
Section titled “画像用のAstroコンポーネント”Astroには画像用の組み込みコンポーネントとして<Image />と<Picture />の2つが用意されているほか、SVGファイルをインポートしてAstroコンポーネントとして使用することもできます。これらのコンポーネントは、.astroコンポーネントをインポートして描画できるすべてのファイルで使用できます。
<Image />
Section titled “<Image />”以下のような画像の最適化バージョンを表示するには、Astro組み込みの<Image />コンポーネントを使用してください。
src/フォルダー内に配置されているローカル画像- 承認済みソースから取得した設定済みのリモート画像
<Image />を使用すると、表示する画像を適切にコントロールできるように、ローカル画像や承認済みリモート画像の寸法、ファイル形式、画質を変換できます。この変換処理は、事前レンダリングされるページではビルド時に行われます。ページがオンデマンドでレンダリングされる場合は、ページが表示されるタイミングで動的に変換されます。生成される<img>タグにはalt、loading、decoding属性が含まれ、Cumulative Layout Shift(CLS)を防ぐために画像のサイズ情報が自動で補完されます。
Cumulative Layout Shift(CLS)は、ページの読み込み中にコンテンツがどれだけずれたかを測定するCore Web Vitalsの指標です。<Image />コンポーネントは、画像に対して正しいwidthとheightを自動的に設定することで、CLSを最適化します。
---// 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&w=1600&h=900&f=webp" <!-- ... -->/><Image />コンポーネントは、HTMLの<img>タグで使用できる任意の属性に加えて、複数のコンポーネントプロパティ (EN)を受け入れます。
次の例では、画像コンポーネントにclassを指定しており、これは最終的に生成される<img>要素に適用されます。
---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=""/>public/フォルダー内の画像や、プロジェクトで明示的に設定されていないリモート画像に対しても、<Image />コンポーネントを使用できます。ただし、これらの画像は最適化や処理の対象にはなりません。出力される画像は、HTMLの<img>を使用した場合と同じになります。
それでも、すべての画像に<Image />コンポーネントを使用することで、一貫した編集体験が得られるだけでなく、最適化されていない画像であってもCumulative Layout Shift(CLS)を防ぐことができます。
<Picture />
Section titled “<Picture />”
追加:
astro@3.3.0
複数の画像形式やサイズを持つ<picture>タグを生成するには、Astro組み込みの<Picture />コンポーネントを使用してください。これにより、優先して表示したいファイル形式を指定しながら、同時にフォールバック用の形式を提供できます。<Image />コンポーネントと同様に、事前レンダリングされるページではビルド時に画像が処理されます。ページがオンデマンドでレンダリングされる場合は、ページが表示されるタイミングで動的に処理されます。
次の例では、<Picture />コンポーネントを使用して、ローカルの.pngファイルをウェブに最適化されたavifおよびwebp形式に変換し、必要に応じて.pngをフォールバックとして表示する<img>を生成しています。
---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のリファレンスを参照してください。
レスポンシブ画像の動作
Section titled “レスポンシブ画像の動作”
追加:
astro@5.10.0
レスポンシブ画像とは、さまざまなデバイス間でパフォーマンスを向上させるために調整される画像のことです。これらの画像はコンテナに合わせてリサイズでき、訪問者の画面サイズや解像度に応じて異なるサイズで配信できます。
<Image />または<Picture />コンポーネントにlayoutプロパティ (EN)を適用すると、Astroは画像に必要なsrcsetおよびsizesの値を自動的に生成し、画像が適切にリサイズされるように必要なスタイルを適用します。
このレスポンシブの動作がimage.layoutによってグローバルに設定 (EN)されている場合、すべての画像コンポーネントに加え、Markdownの![]()構文を使用するすべてのローカル画像およびリモート画像にも適用されます。
なお、public/フォルダー内の画像は最適化の対象外であり、レスポンシブ画像はサポートされていません。
1つのレスポンシブ画像から異なるサイズの複数の画像が生成されるため、ブラウザは訪問者に対して最適な画像を表示できます。
事前レンダリングされるページの場合、この処理はビルド時に実行されるため、特に画像が多数あるプロジェクトではビルド時間が増加する可能性があります。
オンデマンドでレンダリングされるページの場合、画像はページへのアクセス時に必要に応じて生成されます。これによりビルド時間には影響しませんが、画像が表示される際に実行される画像変換処理の回数が増加する可能性があります。利用している画像サービスによっては、追加コストが発生する場合があります。
レスポンシブ画像用に生成されるHTML出力
Section titled “レスポンシブ画像用に生成されるHTML出力”デフォルト設定または個別のコンポーネントでlayoutが指定されている場合、画像の寸法とlayoutの種類に基づいて、srcsetおよびsizes属性が自動的に生成されます。constrainedまたはfull-widthレイアウトが適用された画像には、コンテナに合わせてリサイズされるようスタイルが適用されます。
---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">レスポンシブ画像のスタイル
Section titled “レスポンシブ画像のスタイル”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)を有効にしないでください。
SVGコンポーネント
Section titled “SVGコンポーネント”
追加:
astro@5.7.0
Astroでは、SVGファイルをインポートしてAstroコンポーネントとして使用できます。Astroは、HTML出力内にSVGのコンテンツをインラインで展開します。
任意のローカル.svgファイルのデフォルトインポートを参照してください。このインポートはAstroコンポーネントとして扱われるため、動的タグを使用する場合と同様の命名規則(大文字で始める、など)に従う必要があります。
---import Logo from './path/to/svg/file.svg';---
<Logo /><Image />やその他のAstroコンポーネントと同様に、SVGコンポーネントをUIフレームワークコンポーネントの内部で直接使用することはできません。ただし、.astroコンポーネント内であれば、フレームワークコンポーネントに渡すことは可能です。
SVGコンポーネントの属性
Section titled “SVGコンポーネントの属性”widthやheight、fill、strokeのほか、ネイティブの<svg>要素で受け入れられる任意の属性をpropsとして渡すことができます。これらの属性は、基礎となる<svg>要素に自動的に適用されます。元の.svgファイルにすでに存在するプロパティに対してコンポーネント経由でpropsを渡した場合は、コンポーネントに渡された値が元の値を上書きします。
---import Logo from '../assets/logo.svg';---
<Logo width={64} height={64} fill="currentColor" />SvgComponent型
Section titled “SvgComponent型”astro@5.14.0
SvgComponent型を使用することで、.svgアセットに対して型安全性を強制することもできます。
---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として属性を受け取って各画像に一貫したスタイルを適用できます。
---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プロパティを含めることを強く推奨します。
src/内の画像
Section titled “src/内の画像”ローカル画像は、対象の.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プロパティを使用しています。
---// ローカル画像をインポートimport myDog from '../../images/pets/local-dog.jpg';---// 画像プロパティにアクセス<img src={myDog.src} width={myDog.width} height={myDog.height} alt="吠えている犬" />public/内の画像
Section titled “public/内の画像”public/内にある画像の場合は、publicフォルダーからの相対ファイルパスをsrcの値として使用します。
<img src="/images/public-cat.jpg" alt="寝ている猫" >リモート画像
Section titled “リモート画像”リモート画像の場合は、画像の完全なURLをsrcの値として使用します。
<img src="https://example.com/remote-cat.jpg" alt="寝ている猫" ><Image />と<img>の使い分け
Section titled “<Image />と<img>の使い分け”<Image />コンポーネントは画像を最適化し、(処理可能な画像について)元の縦横比に基づいてwidthとheightを自動推測することでCLSを防ぎます。可能な限り、.astroファイル内ではこのコンポーネントを使用することが推奨されます。
<Image />コンポーネントを使用できない以下のようなケースではHTMLの<img>要素を使用してください。
- サポートされていない画像形式を扱う場合
- Astroによる画像の最適化を行いたくない場合
- クライアントサイドで
src属性に動的にアクセス・変更する場合
CMSまたはCDNからの画像の使用
Section titled “CMSまたはCDNからの画像の使用”画像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リファレンスを参照してください。
リモート画像の承認
Section titled “リモート画像の承認”image.domains (EN)およびimage.remotePatterns (EN)を使用して、画像最適化の対象として承認する画像ソースURLのドメインやパターンのリストを設定できます。この設定は、外部ソースの画像を表示する際にサイトを保護するための追加のセキュリティ層となります。
承認されたソース以外のリモート画像は最適化されませんが、これらの画像に<Image />コンポーネントを使用することで、Cumulative Layout Shift(CLS)を防ぐことができます。
たとえば、次の設定ではastro.buildからのリモート画像のみが最適化を許可されます。
export default defineConfig({ image: { domains: ["astro.build"], }});次の設定では、HTTPSホストからのリモート画像のみが許可されます。
export default defineConfig({ image: { remotePatterns: [{ protocol: "https" }], }});コンテンツコレクション内の画像
Section titled “コンテンツコレクション内の画像”現在のフォルダーからの相対パスを使用することで、ブログ記事のカバー画像など、コンテンツコレクションのエントリに関連付けられた画像をフロントマター内で宣言できます。
---title: "初めてのブログポスト"cover: "./firstpostcover.jpeg" # "src/content/blog/firstpostcover.jpeg"に解決されますcoverAlt: "山々の背後に沈む夕日の写真。"---
これはブログポストです。コンテンツコレクションスキーマのimageヘルパーを使用すると、画像の検証とインポートを行えます。
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として渡すことができるようになります。
以下の例は、先ほどのスキーマに基づいて各ブログ記事のカバー写真とタイトルをレンダリングするブログインデックスページを示しています。
---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()による画像の生成
Section titled “getImage()による画像の生成”getImage()関数は、APIルートなど、HTML内に直接出力する以外の場所で使用するための画像を生成することを目的としています。<Picture>や<Image>コンポーネントで現在サポートされていないオプションが必要な場合は、getImage()関数を使用して独自のカスタム<Image />コンポーネントを作成できます。
getImage()はサーバー側でのみ使用できます。生成された画像URLをクライアント側(クライアントサイドのスクリプトやフレームワークコンポーネント内など)で使用する必要がある場合は、フロントマター内でgetImage()を呼び出し、結果のsrcをクライアントに渡してください。
---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テキスト
Section titled “Altテキスト”すべてのユーザーが同じように画像を視認できるわけではないため、画像を使用する際にはアクセシビリティへの配慮が特に重要です。画像にはalt属性を使用して、わかりやすい代替テキストを指定してください。
この属性は、<Image />と<Picture />両方のコンポーネントで必須です。altテキストが指定されていない場合、alt属性を含めることを促すわかりやすいエラーメッセージが表示されます。
画像が単なる装飾目的である場合(ページの理解に寄与しない場合)は、スクリーンリーダーがその画像を無視できるようにalt=""を設定してください。
デフォルトの画像サービス
Section titled “デフォルトの画像サービス”astro:assetsで使用されるデフォルトの画像サービスはSharpです。image.service (EN)オプションを使用して、画像サービスをさらに設定できます。
pnpmのような厳格なパッケージマネージャーを使用している場合、SharpがAstroの依存関係であっても、プロジェクトに手動でインストールする必要がある場合があります。
pnpm add sharpno-opパススルーサービスの設定
Section titled “no-opパススルーサービスの設定”使用しているアダプターがAstro組み込みのSharpによる画像最適化をサポートしていない場合(例:Cloudflare)、no-op(何もしない)画像サービスを設定することで<Image />や<Picture />コンポーネントを使用できるように設定できます。これらの環境では、Astroによる画像変換や処理は一切行われないことに注意してください。ただし、Cumulative Layout Shift(CLS)の防止、alt属性の強制、一貫した編集体験など、astro:assetsを使用するその他のメリットは引き続き享受できます。
Sharpによる画像処理を回避するには、passthroughImageService()を設定します。
import { defineConfig, passthroughImageService } from 'astro/config';
export default defineConfig({ image: { service: passthroughImageService() }});アセットキャッシュ
Section titled “アセットキャッシュ”Astroは、ローカル画像と承認されたソースからのリモート画像の両方について、サイトビルド時に処理済み画像アセットをキャッシュディレクトリに保存します。ビルド間でキャッシュディレクトリを保持することにより、処理済みアセットが再利用され、ビルド時間と帯域幅の使用量が改善されます。
デフォルトのキャッシュディレクトリは./node_modules/.astroですが、cacheDir (EN)設定オプションを使用して変更できます。
リモート画像
Section titled “リモート画像”アセットキャッシュ内のリモート画像はHTTPキャッシュに基づいて管理され、リモートサーバーから返されるCache-Controlヘッダーを尊重します。 画像はCache-Controlヘッダーで許可されている場合にキャッシュされ、新鮮でなくなるまで使用されます。
追加:
astro@5.1.0
再検証は、期限切れになったキャッシュ画像が現在も最新であるかどうかをリモートサーバーに問い合わせることで、帯域幅の使用量とビルド時間を削減します。サーバーが画像はまだ新鮮であると応答した場合はキャッシュされたバージョンが再利用され、そうでない場合は画像が再ダウンロードされます。
再検証を行うには、リモートサーバーがレスポンスにLast-ModifiedヘッダーやETag(エンティティタグ)ヘッダーを含めて送信する必要があります。この機能は、If-Modified-SinceおよびIf-None-Matchヘッダーをサポートしているリモートサーバーで利用できます。
コミュニティインテグレーション
Section titled “コミュニティインテグレーション”Astroプロジェクトで画像を最適化したり操作したりするための、サードパーティ製のコミュニティ画像インテグレーションがいくつか提供されています。
Learn