コンテンツにスキップ

画像

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

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

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

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

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

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

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

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

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

src/pages/blog/MyImages.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="鳥。">

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

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

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

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

現在、組み込みのassets機能には<Picture />コンポーネントは含まれていません。

代わりに、アートディレクションやレスポンシブ画像を作成するために、HTMLの画像属性srcsetsizesまたは<picture>タグを使用して、getImage()により画像やカスタムコンポーネントを生成できます。

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

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

    src/pages/index.astro
    ---
    import { Image } from 'astro:assets';
    import myImportedImage from `../assets/my-local-image.png`
    ---
    <Image src={myImportedImage} alt="説明文" />
  • public/フォルダ内の画像 - 画像のpublicフォルダを起点としたファイルパスを使用します。

    src/pages/index.astro
    ---
    import { Image } from 'astro:assets';
    ---
    <Image
    src="/images/my-public-image.png"
    alt="説明文"
    width="200"
    height="150"
    />
  • リモート画像 - 画像のフルURLをプロパティ値として使用します。

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

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

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

widthとheight (public/とリモート画像の場合は必須)
セクションタイトル: widthとheight (public/とリモート画像の場合は必須)

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

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

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

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

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

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

  • フォーマット間で自動的に正規化されるプリセット(lowmidhighmax)。
  • (フォーマット間で異なる解釈となる)0から100までの数値。

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

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

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

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

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

src/components/BlogPostImage.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>

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

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

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

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

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

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

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

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

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

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

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

<Image />コンポーネントは、画像を最適化し、また(ローカル画像の場合は)オリジナルのアスペクト比に基づいて幅と高さを推測することでCLSを回避します。ただし、特定のフォーマットのみに対応しており、<picture>要素はなく、srcsetもサポートしていません。

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

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

image.domainsimage.remotePatternsを使用して、画像の最適化に使用する、許可された画像ソースの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" }],
}
});

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

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

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

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インテグレーション (EN)を使用します。

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

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

src/pages/post-1.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)

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

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

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

src/content/config.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として渡すことができます。

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

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

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="満天の星空。" />

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

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

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

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

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

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

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

{
options: {...} // 渡されたオリジナルのパラメータ
src: "https//..." // 生成された画像へのパス
attributes: {...} // 画像をレンダリングするために必要な追加のHTML属性(width、height、styleなど)
}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

src/env.d.ts
/// <reference types="astro/client-image" />
/// <reference types="astro/client" />

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

src/pages/posts/post-1.astro
---
import rocket from '~/assets/rocket.png'
import rocket from '../../assets/rocket.png';
---

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

セクションタイトル: 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画像サービスを設定できます。

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

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

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

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

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

src/components/MyComponent.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="宇宙に浮かぶロケット。" />

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

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

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

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

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

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

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

    astro.config.mjs
    import { defineConfig } from 'astro/config';
    import image from '@astrojs/image';
    export default defineConfig({
    integrations: [
    image(),
    ]
    })
  2. (必要に応じて)型を更新します。

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

    src/env.d.ts
    /// <reference types="@astrojs/image/client" />
    /// <reference types="astro/client" />

    同様に、必要に応じてtsconfig.jsonを更新します。

    tsconfig.json
    {
    "compilerOptions": {
    "types": ["@astrojs/image/client"]
    "types": ["astro/client"]
    }
    }
  3. 既存の<Image />コンポーネントを移行します。

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

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

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

    src/components/MyComponent.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. 既存の<Picture />コンポーネントを削除します。

    現在、組み込みのアセット機能には<Picture />コンポーネントは含まれていません。

    代わりに、HTMLの画像属性srcsetsizes、または<picture>タグを使用して、アートディレクションやレスポンシブ画像を作成できます。

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

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

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

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

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

セクションタイトル: コンテンツコレクションのスキーマを更新する

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

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

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

src/pages/blog/MyImages.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の両方を組み合わせることが、シームレスに画像を扱うための正しい方法かもしれません。