import Since from '/components/Since.astro'; import PackageManagerTabs from '/components/tabs/PackageManagerTabs.astro';

import RecipeLinks from "~/components/RecipeLinks.astro";

Astroでは、プロジェクト内にローカルに保存された画像、外部URLにリンクされた画像、CMSやCDNで管理されている画像などについて、これらをサイト上で使用するためのいくつかの方法を提供しています。

画像を保存する場所

src/とpublic/

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

src/に保存されているローカル画像は、プロジェクト内のすべてのファイル（.astro、.md、.mdx、.mdoc、その他のUIフレームワーク）で使用できます。画像は、コンテンツと同じ場所など、任意のフォルダに保存できます。

画像に対する処理を避けたい場合や、画像へのリンクを直接公開したい場合は、画像をpublic/フォルダに保存します。

リモート画像

コンテンツ管理システム（CMS）やデジタルアセット管理（DAM）プラットフォームなど、リモートに画像を保存することもできます。

外部ソースを扱う際の保護を強化するために、設定で指定した許可された画像ソースからのリモート画像のみ処理されます。ただし、リモート画像の表示は常に可能です。

Astroは、APIを使用してリモートからデータを取得したり、画像をそのフルURLパスから表示したりできます。一般的なサービスを組み込む例については、CMSガイドを確認してください。

.astroファイル内の画像

.astroファイルでローカル画像を使用するには、ファイルにインポートする必要があります。リモートとpublic/の画像はインポートする必要はありません。

astro:assetsからAstro組み込みの<Image />コンポーネントをインポートして使用すると、画像を最適化できます。また、Astro構文ではHTMLの<img>タグを直接書くこともできますが、画像処理はスキップされます。

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="鳥。">

src/フォルダーから動的に画像を読み込むには、次のレシピを参考にしてください:

<RecipeLinks slugs={["ja/recipes/dynamically-importing-images" ]}/>

<Image /> (astro:assets)

Astro組み込みの<Image />コンポーネントを使用して、ローカル画像と設定済みのリモート画像の最適化版を表示できます。

public/フォルダ内の画像とプロジェクトで明示的に設定されていないリモート画像もImageコンポーネントで使用できますが、最適化処理はおこなわれません。

<Image />は、ローカルまたは許可されたリモート画像のサイズ、ファイルタイプ、品質を変換して、表示される画像を制御します。生成された<img>タグには、alt、loading、decoding属性が含まれており、また Cumulative Layout Shift（CLS） を回避するために画像のサイズを推測します。

:::tip[Cumulative Layout Shiftとは？] Cumulative Layout Shift（CLS）は、ローディング中にページのコンテンツがどれだけ移動したかを測定するためのCore Web Vitalのメトリックです。<Image />コンポーネントは、ローカル画像の正しいwidthとheightを自動的に設定することで、CLSへと最適化します。 :::

astro
---// Imageコンポーネントと画像をインポートするimport { Image } from 'astro:assets';import myImage from "../assets/my_image.png"; // 画像は1600x900---<!-- `alt`はImageコンポーネントでは必須です --><Image src={myImage} alt="画像の説明。" />
html
<!-- 出力 --><!-- 画像は最適化され、適切な属性が必ず付与されます --><img  src="/_astro/my_image.hash.webp"  width="1600"  height="900"  decoding="async"  loading="lazy"  alt="画像の説明。"/>

プロパティ

src (必須)

画像ファイルのsrc値の形式は、画像ファイルの場所によって異なります。

  • src/内のローカル画像 - 相対ファイルパスを使用するか、またはインポートエイリアスを設定して**、画像もインポート**する必要があります。インポート名をsrc値として使用します。

    astro
    ---import { Image } from 'astro:assets';import myImportedImage from `../assets/my-local-image.png`---<Image src={myImportedImage} alt="説明文" />

  • public/フォルダ内の画像 - 画像のpublicフォルダを起点としたファイルパスを使用します。

    astro
    ---import { Image } from 'astro:assets';---<Image   src="/images/my-public-image.png"  alt="説明文"  width="200"  height="150"/>

  • リモート画像 - 画像のフルURLをプロパティ値として使用します。

    astro
    ---import { Image } from 'astro:assets';---<Image   src="https://example.com/remote-image.jpg"  alt="説明文"  width="200"  height="150"/>
alt (必須)

必須のalt属性を使用して、画像の説明的な代替テキストの文字列を記述します。

画像が単に装飾用である場合（つまり、ページの理解に貢献していない場合）、スクリーンリーダーやその他の支援技術に画像を無視するよう伝えるために、alt=""を設定します。

widthとheight (public/とリモート画像の場合は必須)

これらのプロパティは、画像に使用するサイズを定義します。

ローカル画像をオリジナルのアスペクト比で使用する場合、widthとheightはソースファイルから自動的に推測されるため、必須ではありません。

ただし、リモート画像とpublic/フォルダに保存されている画像については、Astroはこれらのファイルを解析できないため、両プロパティは必須となります。

densities

生成する画像のピクセル密度の配列です。

この値を指定すると、<img>タグのsrcset属性を生成するために使用されます。この値を使用する場合はwidthsを使用しないでください。

元の画像以上の濃度になる値が指定されると、画像のアップスケーリングを避けるために無視されます。

astro
---import { Image } from 'astro:assets';import myImage from "../assets/my_image.png";---<Image src={myImage} width={myImage.width / 2} densities={[1.5, 2]} alt="説明文" />
html
<img  src="/_astro/my_image.hash.webp"  srcset="    /_astro/my_image.hash.webp 1.5x    /_astro/my_image.hash.webp 2x  "  alt="説明文"  width="800"  height="450"  loading="lazy"  decoding="async"/>
widths

生成する画像の幅の配列です。

この値を指定すると、<img>タグのsrcset属性を生成するために使用されます。また、sizesプロパティも指定する必要があります。

この値を使用する場合はdensitiesを使用しないでください。srcset属性を生成するために使用できるのは、どちらかひとつの値になります。

元の画像以上の幅が指定されると、画像のアップスケーリングを避けるために無視されます。

astro
---import { Image } from 'astro:assets';import myImage from "../assets/my_image.png"; // 画像は1600x900---<Image  src={myImage}  widths={[240, 540, 720, myImage.width]}  sizes={`(max-width: 360px) 240px, (max-width: 720px) 540px, (max-width: 1600px) 720px, ${myImage.width}px`}  alt="説明文"/>
html
<img  src="/_astro/my_image.hash.webp"  srcset="    /_astro/my_image.hash.webp 240w,    /_astro/my_image.hash.webp 540w,    /_astro/my_image.hash.webp 720w,		/_astro/my_image.hash.webp 1600w  "  sizes="    (max-width: 360px) 240px,    (max-width: 720px) 540px,    (max-width: 1600px) 720px,    1600px  "  alt="説明文"  width="1600"  height="900"  loading="lazy"  decoding="async"/>
format

オプションで、使用する画像ファイルタイプの出力を指定できます。

デフォルトでは、<Image />コンポーネントは.webpファイルを出力します。

quality

qualityはオプションのプロパティで、次のいずれかの値を取ります。

  • フォーマット間で自動的に正規化されるプリセット（low、mid、high、max）。
  • （フォーマット間で異なる解釈となる）0から100までの数値。
その他のプロパティ

以上のプロパティに加えて、<Image />コンポーネントは、HTMLの<img>タグに設定可能なすべてのプロパティを受け付けます。

たとえば、最終的な<img>要素にclassを指定できます。

astro
---import { Image } from 'astro:assets';import myImage from "../assets/my_image.png";---<!-- `alt`はImageコンポーネントにおいて必須です --><Image src={myImage} alt="" class="my-class" />
html
<!-- 出力 --><img  src="/_astro/my_image.hash.webp"  width="1600"  height="900"  decoding="async"  loading="lazy"  class="my-class"  alt=""/>

デフォルト値の設定

現在、すべての<Image />コンポーネントに対してデフォルト値を指定する方法はありません。必須属性は個々のコンポーネントに設定する必要があります。

再利用性を高めるための代替案として、<image />コンポーネントを別のAstroコンポーネントでラップできます。たとえば以下のようにして、ブログ記事の画像用コンポーネントを作成できます。

astro
---import { Image } from 'astro:assets';const {src, ...attrs} = Astro.props;---<Image src={src} {...attrs} /><style>  img :global(img), svg {    margin-block: 2.5rem;    border-radius: 0.75rem;  }</style>

<Picture />

Astro組み込みの<Picture />コンポーネントを使用することで、複数のフォーマットやサイズでのレスポンシブな画像を表示できます。

astro
---import { Picture } from 'astro:assets';import myImage from "../assets/my_image.png"; // 画像は1600x900---<!-- `alt` is mandatory on the Picture component --><Picture src={myImage} formats={['avif', 'webp']} alt="説明文" />
html
<!-- Output --><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 />コンポーネントでは<Image />コンポーネントの全てのプロパティと、以下のプロパティが使用できます。

formats

<source>タグに使用するフォーマットの配列です。この配列の順番で<source>要素として追加され、表示するフォーマットが決定されます。最適なパフォーマンスのためには、最新のフォーマット(例：webpやavif)を最初に追加してみてください。デフォルトでは['webp']が設定されています。

fallbackFormat

<img>タグのフォールバック値として使用するフォーマットです。

それぞれデフォルトとして、静止画像の場合は.png、アニメーション画像の場合は.gif、そしてSVGファイルの場合は.svgが設定されています。

pictureAttributes

<picture>タグに追加する属性のオブジェクト。

このプロパティは、外側の<picture>要素自体に属性を適用するために使用します。直接<Picture />コンポーネントに適用される属性は、画像変換に使用されるものを除き、内側の<img>要素に適用されます。

astro
---import { Picture } from "astro:assets";import myImage from "../my_image.png"; // 画像は1600x900---<Picture src={myImage} alt="説明文" pictureAttributes={{style: "background-color: red;"}} />
html
<picture style="background-color: red;">  <source srcset="/_astro/my_image.hash.webp" type="image/webp" />  <img    src="/_astro/my_image.hash.png"    alt="説明文"    width="1600"    height="900"    loading="lazy"    decoding="async"  /></picture>

<img>

Astroテンプレートの構文では、最終的な出力を完全に制御可能な<img>タグを直接書くこともできます。これらの画像は処理されず、最適化もされません。

すべてのHTMLの<img>タグのプロパティを記述でき、必須のプロパティはsrcのみです。

src/内のローカル画像

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

たとえば、CLSを回避しCore Web Vitalsを改善するために、画像のheightとwidthプロパティを使用します。

astro
---// ローカル画像のインポートimport myDog from `../../images/pets/local-dog.jpg`---// 画像のプロパティにアクセス<img src={myDog.src} width={myDog.width} height={myDog.height} alt="吠える犬。" />

インポートされた画像アセットは、以下のシグネチャと一致します。

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

public/内の画像

public/にある画像の場合は、srcの値に画像のpublicフォルダを起点としたファイルパスを使用します。

astro
<img src="/images/public-cat.jpg" alt="眠る猫。">

リモート画像

リモート画像の場合は、srcの値に画像のフルURLを使用します。

astro
<img src="https://example.com/remote-cat.jpg" alt="眠る猫。">

<Image />と<img>の選択

<Image />コンポーネントは、画像を最適化し、また（ローカル画像の場合は）オリジナルのアスペクト比に基づいて幅と高さを推測することでCLSを回避します。

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

  • サポートされていない画像フォーマット
  • Astroによる画像の最適化が不要な場合
  • クライアントサイドでsrc属性に動的にアクセスして変更する場合

リモート画像の許可

image.domainsとimage.remotePatternsを使用して、画像の最適化に使用する、許可された画像ソースのURLドメインとパターンのリストを設定できます。この設定は、外部ソースから画像を表示する際にサイトを保護するために追加の安全性を提供します。

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

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

ts
// astro.config.mjsexport default defineConfig({  image: {    domains: ["astro.build"],  }});

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

ts
// astro.config.mjsexport default defineConfig({  image: {    remotePatterns: [{ protocol: "https" }],  }});

CMSやCDNの画像の使用

画像CDNは、Astroのすべての画像オプションと互換性があります。<Image />コンポーネント、<img>タグ、またはMarkdown記法のsrc属性に、画像のフルURLを指定してください。リモート画像の最適化には、許可されたドメインまたはURLパターンを設定する必要があります。

あるいは、CDNがNode.js SDKを提供している場合は、プロジェクトでそれを使用することも可能です。たとえばCloudinaryのSDKは、適切なsrcをもつ<img>タグを生成してくれます。

Markdownファイル内の画像

.mdファイルでは、Markdown標準の![alt](src)構文を使用します。この構文は、Astroの画像サービスAPIと連携して、ローカル画像と許可されたリモート画像を最適化します。

md
<!-- src/pages/post-1.md --># 私のMarkdownページ<!-- src/assets/に置かれたローカル画像 --><!-- 相対ファイルパスかImportエイリアスを使用します -->![満天の星空](../assets/stars.png)<!-- public/images/に置かれた画像 --><!-- public/からの相対パスを使用します -->![満天の星空](/images/stars.png)<!-- 別のサーバー上のリモート画像 --><!-- 画像の完全なURLを使用します -->![Astro](https://example.com/images/remote-image.png)

ローカル画像の場合<img>タグはサポートされておらず、また.mdファイルでは<Image />コンポーネントは使用できません。

画像の属性をより細かく制御する必要がある場合は、Markdown構文に加えて、Astroの<Image />コンポーネントや、JSXの<img />タグを使用可能な.mdxファイル形式を使用することをおすすめします。AstroにMDXサポートを追加するには、MDXインテグレーションを使用します。

MDXファイル内の画像

コンポーネントと画像をインポートすることで、.mdxファイル内でAstroの<Image />コンポーネントとJSXの<img />タグを使用できます。使い方は.astroファイルの場合と同様です。

さらに、インポート不要でMarkdown標準の![alt](src)構文もサポートされています。

mdx
---title: 私のページタイトル---import { Image } from 'astro:assets';import rocket from '../assets/rocket.png';# 私のMDXページ// 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)

コンテンツコレクションと画像

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

md
---title: "私の最初のブログ記事"cover: "./firstpostcover.jpeg" # "src/content/blog/firstblogcover.jpeg"へと解決されますcoverAlt: "山々の向こうに沈む夕日の写真。"---これはブログ記事です

コンテンツコレクションスキーマのimageヘルパーにより、Zodを使用して画像のメタデータを検証できます。

ts
import { defineCollection, z } from "astro:content";const blogCollection = defineCollection({	schema: ({ image }) => z.object({		title: z.string(),		cover: image().refine((img) => img.width >= 1080, {			message: "カバー画像は幅1080ピクセル以上でなければなりません！",		}),		coverAlt: z.string(),	}),});export const collections = {	blog: blogCollection,};

画像はインポートされ、メタデータへと変換されます。これにより、<Image/>、<img>、そしてgetImage()に、srcとして渡すことができます。

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

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.slug}>{post.data.title}</a>			</h2>		</div>	))}

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

UIフレームワークコンポーネントに画像を追加する場合は、フレームワーク独自の画像構文を使用して画像をレンダリングします（たとえば、JSXの<img />、Svelteの<img>などです）。

ローカル画像は、srcなどの画像プロパティにアクセスするために最初にインポートする必要があります。

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

Imageコンポーネントを渡す

<Image />コンポーネントは、他のAstroコンポーネントと同様に、UIフレームワークコンポーネントでは使用できません。

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

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

getImage()で画像を生成する

:::caution getImage()はサーバー専用のAPIに依存しており、クライアントで使用するとビルドが失敗します。 :::

getImage()関数は、たとえばAPIルートなど、HTML以外の場所で使用する画像を生成することを目的としています。また、これを使って独自のカスタム<Image />コンポーネントも作成できます。

<RecipeLinks slugs={["ja/recipes/build-custom-img-component" ]}/>

getImage()は、（altを除く）Imageコンポーネントと同じプロパティをもつオプションオブジェクトを受け取ります。

astro
---import { getImage } from "astro:assets";import myBackground from "../background.png"const optimizedBackground = await getImage({src: myBackground, format: 'webp'})---<div style={`background-image: url(${optimizedBackground.src});`}></div>

getImage()は以下のプロパティをもつオブジェクトを返します。

js
{  rawOptions: {...}, // オリジナルのパラメータを渡す  options: {...}, // 有効なパラメータを渡す  src: "https//...", // 生成された画像へのパス  srcSet: {    values: [...], // 生成されたsrcsetの値。各エントリーはurlとサイズ記述子を持つ。    attribute: "", // valuesから生成されたsrcset属性  }  attributes: {...} // 画像をレンダリングするために必要な追加のHTML属性（width、height、styleなど）}

代替テキスト

すべてのユーザーが同じように画像を見れるわけではないため、画像を使用する際のアクセシビリティは特に重要です。画像に対して説明的な代替テキストを提供するために、alt属性を使用してください。

この属性は<Image />コンポーネントでは必須です。代替テキストが指定されていない場合、<Image />はエラーをスローします。

画像が単に装飾用である場合（つまり、ページの理解に貢献していない場合）は、alt=""を設定して、スクリーンリーダーが画像を無視するようにしてください。

デフォルトの画像サービス

Sharpは、astro:assetsで使用されるデフォルトの画像サービスです。

:::note pnpmのような厳格なパッケージマネージャーを使用している場合は、Astroの依存関係であるにもかかわらず、プロジェクトにSharpを手動でインストールする必要があるかもしれません。

bash
pnpm add sharp

:::

Squooshの設定

画像を変換するためにSquooshを使用したい場合は、以下のように設定を更新してください。

js
import { defineConfig, squooshImageService } from 'astro/config';export default defineConfig({  image: {    service: squooshImageService(),  },});

no-opパススルーサービスの設定

もし使用しているserverまたはhybridモードのアダプターが、Astroの組み込みのSquooshおよびSharp画像最適化（Deno、Cloudflareなど）をサポートしていない場合、<Image />や<Picture />コンポーネントを使用できるようにno-op画像サービスを設定することができます。Astroはこれらの環境では画像の変換や処理をおこないませんが、Cumulative Layout Shift（CLS）がなくなること、alt属性が必須であること、一貫したコードの書き心地など、astro:assetsを使用した場合の他の利点は享受することができます。

SquooshとSharpの画像処理を回避するpassthroughImageService()の設定:

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

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

Astroプロジェクトで画像を最適化したり、画像を扱ったりするための、サードパーティのコミュニティインテグレーションがあります。

v2.xからv3.0へのアップグレード

Astro v3.0では、astro:assetsは実験的な機能ではなくなりました。

<Image />は組み込みのコンポーネントとなり、以前の@astrojs/imageインテグレーションは削除されました。

これらのことと、Astroで画像を使用するためのその他の変更により、以前のバージョンからAstroプロジェクトをアップグレードすると、いくつかの破壊的な変更が発生する可能性があります。

Astro v2.xプロジェクトをv3.0にアップグレードするには、以下の手順に適切に従ってください。

experimental.assetsからのアップグレード

以前にastro:assetsの実験的なフラグを有効にしていた場合は、Astro v3.0ではデフォルトでアセット機能が含まれているため、プロジェクトを更新する必要があります。

experimental.assetsフラグの削除

実験的なフラグを削除します。

js
import { defineConfig } from 'astro/config';export default defineConfig({  experimental: {    assets: true  }});

必要に応じて、astro/client-imageへの参照をastro/clientに置き換えるために、src/env.d.tsファイルも更新します。

ts
/// <reference types="astro/client-image" />/// <reference types="astro/client" />

~/assetsインポートエイリアスの削除

このImportエイリアスは、astro:assetsにデフォルトで含まれなくなりました。実験的なアセット機能でこのエイリアスを使用していた場合は、相対ファイルパスに変換するか、自分でImportエイリアスを作成する必要があります。

astro
---import rocket from '~/assets/rocket.png'import rocket from '../../assets/rocket.png';---

Cloudflare、Deno、Vercel Edge、Netlify Edge向けのシンプルなアセットサポートを追加する

Astro v3.0では、Astro組み込みのSquooshとSharpによる画像最適化をサポートしていないCloudflare、Deno、Vercel Edge、Netlify Edgeでも、astro:assetsをエラーなしで動作させることができます。Astroはこれらの環境では画像の変換や処理をおこないませんが、Cumulative Layout Shift（CLS）がなくなること、alt属性が必須であること、一貫したコードの書き心地など、astro:assetsを使用した場合の他の利点は享受することができます。

こうした制約のために以前astro:assetsの使用を避けていた場合でも、もう問題なく使用できるようになりました。この動作を明示的に有効にするために、no-op画像サービスを設定できます。

js
import { defineConfig } from 'astro/config';export default defineConfig({  image: {    service: {      entrypoint: 'astro/assets/services/noop'    }  }});

画像を保存する場所を決める

画像を保存する場所を決めるには、今読んでいるこのガイドを参照してください。astro:assetsがもたらす柔軟性を活用して、画像を保存するための新しいオプションを利用したい場合があるかもしれません。たとえば、プロジェクトのsrc/からの相対画像は、Markdown、MDX、MarkdocいずれにおいてもMarkdown標準の![alt](src)構文により参照できるようになりました。

既存の<img>タグを更新する

以前は画像をインポートすると、画像のパスを含む単純なstringが返されました。現在は、インポートされた画像アセットは以下のシグネチャをもつオブジェクトとなります。

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

（UIフレームワークコンポーネント内の画像を含む）既存の<img>タグのsrc属性の更新が必要です。また、インポートした画像から利用できるようになった他の属性も更新できます。

astro
---import rocket from '../images/rocket.svg';---<img src={rocket} width="250" height="250" alt="宇宙に浮かぶロケット。" /><img src={rocket.src} width={rocket.width} height={rocket.height} alt="宇宙に浮かぶロケット。" />

Markdown、MDX、Markdocファイルを更新する

プロジェクトのsrc/からの相対画像は、Markdown、MDX、MarkdocいずれにおいてもMarkdown標準の![alt](src)構文により参照できるようになりました。

これにより、画像をpublic/ディレクトリからプロジェクトのsrc/に移動し、処理を加えて最適化できます。public/内の既存の画像とリモート画像は引き続き有効ですが、Astroのビルドプロセスでは最適化されません。

md
# 私のMarkdownページ<!-- ローカル画像が可能になりました！ -->![満天の星空。](../../images/stars.png)<!-- 画像をコンテンツの近くにキープできます！ -->![満天の星空。](./stars.png)

画像の属性をより細かく制御する必要がある場合は、Markdown構文に加えて、Astroの<Image />コンポーネントやJSXの<img />タグを使用可能な.mdxファイル形式を使用することをおすすめします。AstroにMDXサポートを追加するには、MDXインテグレーションを使用します。

@astrojs/imageを削除する

Astro v2.xで画像インテグレーションを使用していた場合は、以下の手順を完了させてください。

  1. @astrojs/imageを削除します。

    インテグレーションを削除するためにアンインストールし、またastro.config.mjsファイルからも削除する必要があります。

    js
    // astro.config.mjsimport { defineConfig } from 'astro/config';import image from '@astrojs/image';export default defineConfig({  integrations: [    image(),  ]})

  2. （必要に応じて）型を更新します。

    src/env.d.tsに@astrojs/imageのための特別な型を設定していた場合、v3へのアップグレードでこのステップが完了していなければ、デフォルトのAstroの型に戻す必要があるかもしれません。

    ```ts title="src/env.d.ts" del={1} ins={2} /// <reference types="@astrojs/image/client" /> /// <reference types="astro/client" /> ``` 同様に、必要に応じて`tsconfig.json`を更新します。 ```json title="tsconfig.json" del={3} ins={4} { "compilerOptions": { "types": ["@astrojs/image/client"] "types": ["astro/client"] } } ```

  3. 既存の<Image />コンポーネントを移行します。

    新しい組み込みの<Image />コンポーネントを使用するために、@astrojs/image/componentsからのimport文をすべてastro:assetsに変更します。

    現在サポートされていない画像アセットのプロパティを削除します。

    たとえば、aspectRatioはもうサポートされていません。これは、widthとheight属性から自動的に推測されるためです。

    astro
    ---import { Image } from '@astrojs/image/components';import { Image } from 'astro:assets'import localImage from "../assets/logo.png";const localAlt = "Astroのロゴ";---<Image  src={localImage}  width={300}  aspectRatio="16:9"  alt={localAlt}/>

  4. デフォルトの画像サービスを選択します。

    Sharpは、astro:assetsで使用されるデフォルトの画像サービスとなりました。Sharpを使用する場合は、特に設定は必要ありません。

    画像を変換するためにSquooshを使用したい場合は、以下のimage.serviceオプションを使用して設定を更新します。

    js
    import { defineConfig, squooshImageService } from 'astro/config';export default defineConfig({  image: {    service: squooshImageService(),  },});

コンテンツコレクションのスキーマを更新する

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

コンテンツコレクションの新しいimageヘルパーにより、Zodを使用して画像のメタデータを検証できるようになりました。コンテンツコレクションで画像を使用する方法について、詳しくはこちらを参照してください。

Astro v3.0での画像インポートの扱い

Astro v3.0で、以前の画像をインポートした際の挙動を維持しなければならず、画像URLの文字列が必要な場合は、以下のように画像パスの末尾に?urlを追加してください。

astro
---import Sprite from '../assets/logo.svg?url';---  <svg>    <use xlink:href={Sprite + '#cart'} />  </svg>

この方法により、URLの文字列を取得できます。なお、Astroは開発中にsrc/パスを使用しますが、ビルド時には/_astro/cat.a6737dd3.pngのようなハッシュ化されたパスを生成することに注意してください。

画像オブジェクト自体を直接扱いたい場合は、.srcプロパティにアクセスできます。この方法は、Core Web Vitalsメトリクスのための画像サイズの調整や、CLSの防止などのタスクに最適です。

新しいインポートの挙動に移行する場合は、?urlと.srcの両方を組み合わせることが、シームレスに画像を扱うための正しい方法かもしれません。

Astro コース