图像

Astro 提供了多种在你的网站上使用图片的方式，无论是本地存储在项目中，通过外部 URL 链接，还是在 CMS 或 CDN 中管理。

Astro 提供了图片和<Picture />组件、Markdown 图片语法处理、SVG 组件，以及图片生成函数来优化和/或转换你的图片。此外，你可以默认配置自动调整大小的响应式图片，或在单独的图片和 <Picture /> 组件上设置响应式属性。

你始终可以选择在 .astro 或 Markdown 文件中使用原生 HTML 元素（如 <img /> 和 <svg> 文件），或者使用文件类型的标准方式（例如 MDX 和 JSX 中的 <img />）。但是，Astro 不会对这些图片执行任何处理或优化。

请参阅 <Image /> 和 <Picture /> 组件的完整 API 参考。

图片存储位置

`src/` vs `public/`

我们建议将本地图片尽可能保留在 src/ 中，以便 Astro 可以对其进行转换、优化和打包。 public/ 目录中的文件将始终按原样提供或复制到构建文件夹中，不进行任何处理。

存储在 src/ 中的本地图片可供项目中的所有文件使用：.astro、.md、.mdx、.mdoc 以及其他 UI 框架作为文件导入。图片可以存储在任何文件夹中，包括与内容并排放置。

如果你想避免任何处理，请将图片存储在 public/ 文件夹中。这些图片作为你域上的 URL 路径可供项目文件使用，并允许你拥有它们的直接公共链接。例如，你的网站图标通常会放在此文件夹的根目录中，以便浏览器可以识别它。

远程图片

你还可以选择将图片远程存储在内容管理系统 (CMS) 或数字资产管理 (DAM) 平台中。Astro 可以使用 API 远程获取你的数据，或从其完整 URL 路径显示图片。

为了在处理外部源时提供额外保护，Astro 的图片组件和辅助函数将仅处理配置中指定的授权图片源中的图片（例如优化、转换）。来自其他源的远程图片将不进行任何处理地显示。

Astro 文件中的图片

选项： <Image />, <Picture />, <img>, <svg>, SVG 组件

Astro 的模板语言允许你使用 Astro 的 <Image /> 组件渲染优化过的图片，并使用 Astro 的 <Picture /> 组件生成多种尺寸和格式的图片。这两个组件都接受响应式图片属性，用于根据容器大小调整图片大小以及响应设备屏幕尺寸和分辨率。

此外，你可以在 .astro 组件中导入并使用SVG 文件作为 Astro 组件。

所有原生 HTML 标签，包括 <img> 和 <svg>，在 .astro 组件中也可用。使用 HTML 标签渲染的图片将不会被处理（例如优化、转换），并将按原样复制到你的构建文件夹中。

对于 .astro 文件中的所有图片，图片 src 属性的值由图片文件位置决定

来自项目 src/ 文件夹的本地图片使用文件相对路径的导入。

图片和 <Picture /> 组件直接使用命名导入（例如 src={rocket}），而 <img> 标签则使用导入的 src 对象属性（例如 src={rocket.src}）。
远程和 public/ 图片使用 URL 路径。

为远程图片提供完整的 URL（例如 src="https://www.example.com/images/my-remote-image.jpg"），或网站上的相对 URL 路径，该路径对应于文件在 public/ 文件夹中的位置（例如对于位于 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="A bird sitting on a nest of eggs." />
<Image src="/images/bird-in-public-folder.jpg" alt="A bird." width="50" height="50" />
<Image src="https://example.com/remote-bird.jpg" alt="A bird." width="50" height="50" />

<img src={localBirdImage.src} alt="A bird sitting on a nest of eggs.">
<img src="/images/bird-in-public-folder.jpg" alt="A bird.">
<img src="https://example.com/remote-bird.jpg" alt="A bird.">

请参阅 <Image /> 和 <Picture /> 组件的完整 API 参考，包括必需和可选属性。

相关教程： 动态导入图片

Markdown 文件中的图片

选项： ![](), <img> (使用公共或远程图片)

在你的 .md 文件中使用标准 Markdown ![alt](src) 语法。存储在 src/ 中的本地图片和远程图片将被处理和优化。当你全局配置响应式图片时，这些图片也将是响应式的。

存储在 public/ 文件夹中的图片永远不会被优化。

# My Markdown Page

<!-- Local image stored in src/assets/ -->
<!-- Use a relative file path or import alias -->
![A starry night sky.](../assets/stars.png)

<!-- Image stored in public/images/ -->
<!-- Use the file path relative to public/ -->
![A starry night sky.](/images/stars.png)

<!-- Remote image on another server -->
<!-- Use the full URL of the image -->
![Astro](https://example.com/images/remote-image.png)

HTML <img> 标签也可以用于显示存储在 public/ 或远程图片，无需任何图片优化或处理。但是，<img> 不支持 src 中的本地图片。

<Image /> 和 <Picture /> 组件在 .md 文件中不可用。如果你需要对图片属性进行更多控制，我们建议使用Astro 的 MDX 集成来添加对 .mdx 文件格式的支持。MDX 允许MDX 中可用的其他图片选项，包括将组件与 Markdown 语法结合使用。

MDX 文件中的图片

选项： <Image />, <Picture />, <img />, ![](), SVG 组件

你可以在 .mdx 文件中使用 Astro 的 <Image /> 和 <Picture /> 组件，只需导入组件和图片即可。它们的使用方式与在 .astro 文件中相同。JSX 的 <img /> 标签也支持未处理的图片，并且使用与 HTML <img> 标签相同的图片导入方式。

此外，还支持标准 Markdown ![alt](src) 语法，无需导入。

---
title: My Page title
---
import { Image } from 'astro:assets';
import rocket from '../assets/rocket.png';

# My MDX Page

// Local image stored in the the same folder
![Houston in the wild](houston.png)

// Local image stored in src/assets/
<Image src={rocket} alt="A rocketship in space." />
<img src={rocket.src} alt="A rocketship in space." />
![A rocketship in space](../assets/rocket.png)

// Image stored in public/images/
<Image src="/images/stars.png" alt="A starry night sky." />
<img src="/images/stars.png" alt="A starry night sky." />
![A starry night sky.](/images/stars.png)

// Remote image on another server
<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 /> 和 <Picture /> 组件的完整 API 参考。

UI 框架组件中的图片

图片选项：框架自己的图片语法（例如 JSX 中的 <img />，Svelte 中的 <img>）

本地图片必须首先被导入才能访问其图片属性，例如 src。然后，它们可以像在该框架自己的图片语法中通常那样进行渲染

import stars from "../assets/stars.png";

export default function ReactImage() {
  return (
    <img src={stars.src} alt="A starry night sky." />
  )
}

<script>
  import stars from '../assets/stars.png';
</script>

<img src={stars.src} alt="A starry night sky." />

Astro 组件（例如 <Image />、<Picture />、SVG 组件）在 UI 框架组件内部不可用，因为客户端孤岛必须只包含其自身框架的有效代码。

但是，你可以将这些组件生成的静态内容作为子组件或使用命名 <slot/> 传递给 .astro 文件中的框架组件。

---
import ReactComponent from './ReactComponent.jsx';
import { Image } from 'astro:assets';
import stars from '~/stars/docline.png';
---

<ReactComponent>
  <Image src={stars} alt="A starry night sky." />
</ReactComponent>

Astro 图片组件

Astro 提供了两个内置的 Astro 图片组件（<Image /> 和 <Picture />），还允许你导入 SVG 文件并将其用作 Astro 组件。这些组件可以在任何可以导入和渲染 .astro 组件的文件中使用。

`<Image />`

使用内置的 <Image /> Astro 组件来显示优化后的版本，可用于

你本地 src/ 文件夹中的图片
来自授权来源的已配置的远程图片

<Image /> 可以转换本地或授权远程图片的尺寸、文件类型和质量，从而控制你的显示图片。对于预渲染页面，此转换发生在构建时。当你的页面按需渲染时，此转换将在页面查看时即时发生。生成的 <img> 标签包括 alt、loading 和 decoding 属性，并推断图片尺寸以避免累计布局偏移 (CLS)。

---
// import the Image component and the image
import { Image } from 'astro:assets';
import myImage from '../assets/my_image.png'; // Image is 1600x900
---

<!-- `alt` is mandatory on the Image component -->
<Image src={myImage} alt="A description of my image." />

<!-- Prerendered output -->
<!-- Image is optimized, proper attributes are enforced -->
<img
  src="/_astro/my_image.hash.webp"
  width="1600"
  height="900"
  decoding="async"
  loading="lazy"
  alt="A description of my image."
/>

<!-- Output rendered on demand-->
<!-- src will use an endpoint generated on demand-->
<img
  src="/_image?href=%2F_astro%2Fmy_image.hash.webp&amp;w=1600&amp;h=900&amp;f=webp"
  <!-- ... -->
/>

<Image /> 组件接受多个组件属性以及 HTML <img> 标签接受的任何属性。

以下示例为图片组件提供了一个 class，该类将应用于最终的 <img> 元素。

---
import { Image } from 'astro:assets';
import myImage from '../assets/my_image.png';
---

<!-- `alt` is mandatory on the Image component -->
<Image src={myImage} alt="" class="my-class" />

<!-- Prerendered output -->
<img
  src="/_astro/my_image.hash.webp"
  width="1600"
  height="900"
  decoding="async"
  loading="lazy"
  class="my-class"
  alt=""
/>

`<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'; // Image is 1600x900
---

<!-- `alt` is mandatory on the Picture component -->
<Picture src={myImage} formats={['avif', 'webp']} alt="A description of my image." />

<!-- Prerendered 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="A description of my image."
  />
</picture>

有关 <Picture /> 组件属性的详细信息，请参阅 astro:assets 参考。

响应式图片行为

添加于： astro@5.10.0

响应式图片是指根据不同设备调整以提高性能的图片。这些图片可以调整大小以适应其容器，并且可以根据访问者的屏幕尺寸和分辨率以不同的大小提供。

通过将响应式图片属性应用于 <Image /> 或 <Picture /> 组件，Astro 将自动为你的图片生成所需的 srcset 和 sizes 值，并应用必要的样式以确保它们正确调整大小。

当此响应式行为全局配置时，它将应用于所有图片组件，以及使用Markdown ![]() 语法的任何本地和远程图片。

你的 public/ 文件夹中的图片永远不会被优化，并且不支持响应式图片。

在 MDN Web 文档上阅读更多关于响应式图片的信息。

响应式图片的生成 HTML 输出

当设置了布局时（无论是默认还是在单独的组件上），图片都会根据其尺寸和布局类型自动生成 srcset 和 sizes 属性。具有 constrained 和 full-width 布局的图片将应用样式，以确保它们根据其容器进行调整大小。

---
import { Image } from 'astro:assets';
import myImage from '../assets/my_image.png';
---
<Image src={myImage} alt="A description of my image." 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="A description of my image"
  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 会应用少量全局样式，以确保你的图片正确调整大小。在大多数情况下，你会希望默认启用这些样式；如果没有额外的样式，你的图片将无法响应。

但是，如果你更喜欢自己处理响应式图片样式，或者在使用 Tailwind 4 时需要覆盖这些默认设置，请保留默认的 false 值。

Astro 应用的全局样式将取决于布局类型，并且旨在为生成的 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 配合使用的响应式图片

Tailwind 4 与 Astro 的默认响应式样式兼容。然而，Tailwind 使用级联层，这意味着其规则的特异性总是低于不使用层的规则，包括 Astro 的响应式样式。因此，Astro 的样式将优先于 Tailwind 样式。要使用 Tailwind 规则而不是 Astro 的默认样式，请不要启用Astro 的默认响应式样式。

SVG 组件

添加于： astro@5.7.0

Astro 允许你导入 SVG 文件并将其用作 Astro 组件。Astro 会将 SVG 内容内联到你的 HTML 输出中。

引用任何本地 .svg 文件的默认导入。由于此导入被视为 Astro 组件，你必须使用与使用动态标签时相同的约定（例如大写）。

---
import Logo from './path/to/svg/file.svg';
---

<Logo />

你的 SVG 组件，如 <Image /> 或任何其他 Astro 组件，在 UI 框架组件内部不可用，但可以传递给 .astro 组件内部的框架组件。

SVG 组件属性

你可以传递 width、height、fill、stroke 等属性，以及原生 <svg> 元素接受的任何其他属性。这些属性将自动应用于底层的 <svg> 元素。如果原始 .svg 文件中存在某个属性并将其传递给组件，则传递给组件的值将覆盖原始值。

---
import Logo from '../assets/logo.svg';
---

<Logo width={64} height={64} fill="currentColor" />

创建自定义图片组件

你可以通过将 <Image /> 或 <Picture/> 组件包装在另一个 Astro 组件中来创建自定义、可复用的图片组件。这使你只需设置一次默认属性和样式。

例如，你可以为博客文章图片创建一个组件，该组件接收属性作为 props 并为每张图片应用一致的样式

---
import { Image } from 'astro:assets';

const { src, ...attrs } = Astro.props;
---
<Image src={src} {...attrs} />

<style>
  img {
    margin-block: 2.5rem;
    border-radius: 0.75rem;
  }
</style>

使用 HTML `<img>` 标签显示未处理的图片

Astro 模板语法也支持直接编写 <img> 标签，并完全控制其最终输出。这些图片将不会被处理和优化。它接受所有 HTML <img> 标签属性，唯一必需的属性是 src。但是，强烈建议包含用于可访问性的 alt 属性。

src/ 中的图片

本地图片必须从现有 .astro 文件的相对路径导入，或者你可以配置并使用导入别名。然后，你可以访问图片的 src 和其他属性，以在 <img> 标签中使用。

导入的图片资产符合以下签名

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

以下示例使用图片自身的 height 和 width 属性来避免累计布局偏移 (CLS) 并提高核心 Web Vitals

---
// import local images
import myDog from '../../images/pets/local-dog.jpg';
---
// access the image properties
<img src={myDog.src} width={myDog.width} height={myDog.height} alt="A barking dog." />

public/ 中的图片

对于位于 public/ 中的图片，请使用图片相对于公共文件夹的文件路径作为 src 值

<img src="/images/public-cat.jpg" alt="A sleeping cat." >

远程图片

对于远程图片，请使用图片的完整 URL 作为 src 值

<img src="https://example.com/remote-cat.jpg" alt="A sleeping cat." >

选择 <Image /> 还是 <img>

<Image /> 组件会优化你的图片，并根据原始宽高比推断宽度和高度（对于它可以处理的图片），以避免 CLS。它是尽可能在 .astro 文件中使用图片的首选方式。

当你无法使用 <Image /> 组件时，例如以下情况，请使用 HTML <img> 元素

对于不支持的图片格式
当你不想让 Astro 优化你的图片时
在客户端动态访问和更改 src 属性

使用来自 CMS 或 CDN 的图片

图片 CDN 适用于所有 Astro 图片选项。在 <Image /> 组件、<img> 标签或 Markdown 标记中使用图片的完整 URL 作为 src 属性。对于远程图片的图片优化，还需要配置你的授权域名或 URL 模式。

或者，CDN 可能会提供自己的 SDK，以便更轻松地集成到 Astro 项目中。例如，Cloudinary 支持一个 Astro SDK，允许你使用其 CldImage 组件轻松插入图片，或一个 Node.js SDK，可以在 Node.js 环境中生成用于 <img> 标签的 URL。

请参阅 <Image /> 和 <Picture /> 组件的完整 API 参考。

授权远程图片

你可以使用 image.domains 和 image.remotePatterns 配置授权图片源 URL 域和模式列表，以进行图片优化。此配置是额外的安全层，可在显示来自外部源的图片时保护你的网站。

来自其他源的远程图片将不会被优化，但使用 <Image /> 组件显示这些图片将防止累计布局偏移 (CLS)。

例如，以下配置将只允许来自 astro.build 的远程图片被优化

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

以下配置将只允许来自 HTTPS 主机的远程图片

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

内容集合中的图片

你可以在 frontmatter 中声明内容集合条目的关联图片，例如博客文章的封面图片，使用其相对于当前文件夹的路径

---
title: "My first blog post"
cover: "./firstpostcover.jpeg" # will resolve to "src/content/blog/firstblogcover.jpeg"
coverAlt: "A photograph of a sunset behind a mountain range."
---

This is a blog post

内容集合 schema 的 image 助手允许你验证和导入图片。

import { defineCollection, z } from "astro:content";

const blogCollection = defineCollection({
  schema: ({ image }) => z.object({
    title: z.string(),
    cover: image(),
    coverAlt: z.string(),
  }),
});

export const collections = {
  blog: blogCollection,
};

图片将被导入并转换为元数据，允许你将其作为 src 传递给 Astro 组件中的 <Image/>、<img> 或 getImage()。

以下示例显示了一个博客索引页面，该页面从上一个 schema 渲染了每篇博客文章的封面照片和标题

---
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>
  ))
}

使用 `getImage()` 生成图片

getImage() 函数旨在生成图片，这些图片将用于 HTML 之外的其他地方，例如在API 路由中。当你需要 <Picture> 和 <Image> 组件目前不支持的选项时，你可以使用 getImage() 函数创建自己的自定义 <Image /> 组件。

有关更多信息，请参阅 getImage() 参考。

相关教程： 构建自定义图片组件

替代文本

并非所有用户都能以相同的方式查看图片，因此在使用图片时，可访问性是一个特别重要的考虑因素。使用 alt 属性为图片提供描述性替代文本。

此属性对于 <Image /> 和 <Picture /> 组件都是必需的。如果未提供替代文本，将提供一条有用的错误消息，提醒你包含 alt 属性。

如果图片仅是装饰性的（即对页面理解没有贡献），请设置 alt=""，以便屏幕阅读器知道忽略该图片。

默认图片服务

Sharp 是 astro:assets 使用的默认图片服务。你可以使用 image.service 选项进一步配置图片服务。

配置无操作直通服务

如果你的适配器不支持 Astro 内置的 Sharp 图片优化（例如 Deno、Cloudflare），你可以配置一个无操作图片服务，以便使用 <Image /> 和 <Picture /> 组件。请注意，Astro 在这些环境中不执行任何图片转换和处理。但是，你仍然可以享受使用 astro:assets 的其他好处，包括没有累计布局偏移 (CLS)、强制的 alt 属性以及一致的创作体验。

配置 passthroughImageService() 以避免 Sharp 图片处理

import { defineConfig, passthroughImageService } from 'astro/config';

export default defineConfig({
  image: {
    service: passthroughImageService()
  }
});

资产缓存

Astro 在网站构建期间将处理过的图片资产存储在缓存目录中，包括本地和授权来源的远程图片。通过在构建之间保留缓存目录，可以重用处理过的资产，从而提高构建时间和带宽使用率。

默认缓存目录是 ./node_modules/.astro，但是可以使用 cacheDir 配置设置进行更改。

远程图片

资产缓存中的远程图片根据HTTP 缓存进行管理，并遵循远程服务器返回的Cache-Control 头。如果 Cache-Control 头允许，图片将被缓存，并一直使用直到它们不再新鲜为止。

重新验证

新增于： astro@5.1.0

重新验证通过检查远程服务器过期的缓存图片是否仍然最新，从而减少带宽使用和构建时间。如果服务器指示图片仍然新鲜，则重用缓存版本，否则重新下载图片。

重新验证要求远程服务器在其响应中发送 Last-Modified 和/或 Etag（实体标签）头。此功能适用于支持 If-Modified-Since 和 If-None-Match 头的远程服务器。

社区集成

有几个第三方社区图片集成，用于优化和处理 Astro 项目中的图片。

贡献社区赞助

图像

图片存储位置

src/ vs public/

远程图片

Astro 文件中的图片

Markdown 文件中的图片

MDX 文件中的图片

UI 框架组件中的图片

Astro 图片组件

<Image />

<Picture />

响应式图片行为

响应式图片的生成 HTML 输出

响应式图片样式

与 Tailwind 4 配合使用的响应式图片

SVG 组件

SVG 组件属性

创建自定义图片组件

使用 HTML <img> 标签显示未处理的图片

src/ 中的图片

public/ 中的图片

远程图片

选择 <Image /> 还是 <img>

使用来自 CMS 或 CDN 的图片

授权远程图片

内容集合中的图片

使用 getImage() 生成图片

替代文本

默认图片服务

配置无操作直通服务

资产缓存

远程图片

重新验证

社区集成

`src/` vs `public/`

`<Image />`

`<Picture />`

使用 HTML `<img>` 标签显示未处理的图片

使用 `getImage()` 生成图片