图像

Astro 为你提供了多种在网站上使用图像的方法，无论它们是本地存储在你的项目内，还是链接到外部 URL，或者在 CMS 或 CDN 中管理的。

Astro 提供 image 和 picture 组件，Markdown 图像语法处理，SVG 组件，以及图像生成函数来优化和/或转换你的图像。

在 .astro 或 Markdown 文件中，你可以选择使用原生 HTML 元素或 SVG 文件来引用图片，或者根据文件类型使用标准方式（例如在 MDX 和 JSX 中使用 <img />）。然而，Astro 不会对这些图片进行任何处理或优化。

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

在哪里存储图像

`src/` vs `public/`

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

你在 src/ 中存储的本地图像可以被项目中的所有文件使用：.astro、.md、.mdx、.mdoc 和其他 UI 框架。图像可以存储在任何文件夹中，包括与你的内容一起。

如果你想要避免对图像做任何处理或者想要直接公开链接到图像，请将图像存储在 public/ 文件夹中。

远程图像

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

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

`.astro` 文件中的图像

在 .astro 文件中，必须从其相对路径导入本地图像。此导入为你的图像提供 src 值。

远程和 public/ 中的图像不需要导入，而是需要为 src 提供 URL（站点上的完整路径或相对路径）。

导入并使用 Astro 原生的 <Image /> 和 <Picture /> 组件来优化图像。Astro 语法也支持直接编写 HTML <img> 标签，这将跳过图像处理。

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

相关操作指南： 动态导入图片

使用 `<Image />` 组件显示优化后的图像

使用内置的 <Image /> Astro 组件显示以下内容的优化版本：

位于 src/ 文件夹中的本地图像
来自授权来源的配置的远程图像

<Image /> 可以转换本地或授权的远程图像的尺寸、文件类型和质量，以便控制显示的图像。对于预渲染页面来说，这种转换发生在构建时。而对于按需渲染页面来说，这种转换则发生在查看页面的一瞬间。生成的 <img> 标签包括 alt、loading 和 decoding 属性，并推断图像尺寸以避免累积布局偏移（CLS）。

---
// 导入 Image 组件和图像
import { Image } from 'astro:assets';
import myImage from '../assets/my_image.png'; // Image is 1600x900
---

<!-- 在 Image 组件上 `alt` 是必须的  -->
<Image src={myImage} alt="A description of my image." />

<!-- 预渲染输出 -->
<!-- 优化图像，强制实施适当的属性 -->
<img
  src="/_astro/my_image.hash.webp"
  width="1600"
  height="900"
  decoding="async"
  loading="lazy"
  alt="A description of my image."
/>

<!-- 按需渲染输出 -->
<!-- src 属性将使用按需生成的端点 -->
<img
  src="/_image?href=%2F_astro%2Fmy_image.hash.webp&amp;w=1600&amp;h=900&amp;f=webp"
  <!-- ... -->
/>

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

以下示例为图像组件提供了一个 class，该 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=""
/>

使用 `<Picture />` 组件创建响应式图像

添加于： astro@3.3.0

使用内置的 <Picture /> Astro 组件来显示具有多种格式和/或尺寸的响应式图像。就像 <Image /> 组件一样，对于预渲染页面来说，这种转换发生在构建时。而对于按需渲染页面来说，这种转换则发生在查看页面的一瞬间。

---
import { Picture } from 'astro:assets';
import myImage from '../assets/my_image.png'; // 图像分辨率为 1600x900
---
<!-- `alt` 属性在 `Picture` 组件中是必需的 -->
<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 /> 组件属性的详细信息，请参阅 astro:assets 参考。

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

Astro 模板语法还支持直接编写 <img> 标签，来完全控制其最终输出。这些图像将不会被处理和优化。它接受所有 HTML <img> 标签属性，唯一必需的属性是 src。

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

导入的图像资源与以下签名匹配：

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

以下示例使用图像自身的 height 和 width 属性来避免累积布局偏移 (CLS) 从而改进核心页面指标：

---
// 导入本地图像
import myDog from '../../images/pets/local-dog.jpg';
---
// 访问图像的属性
<img src={myDog.src} width={myDog.width} height={myDog.height} alt="一只狂吠的狗。" />

`public/` 中的图像

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

<img src="/images/public-cat.jpg" alt="一只睡觉的猫。" >

远程图像

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

<img src="https://example.com/remote-cat.jpg" alt="一只睡觉的猫。">

选择 `<Image />` 还是 `<img>`

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

当你不能使用 <Image /> 组件时，请使用 HTML <img> 元素，例如：

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

设置默认值

目前，没有办法为所有 <Image /> 或者 <Picture/> 组件指定默认值。应该在每个单独的组件上设置必需的属性。

作为替代方案，你可以在另一个 Astro 组件中封装这些组件以便复用。例如，你可以为博客文章图像创建一个组件，该组件接收 attributes 作为参数并对每个图像应用一样的样式：

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

授权远程图像

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

来自其他来源的远程图像不会被优化，但是使用 <Image /> 组件可以防止累积布局移位（CLS）。

例如，以下配置将只允许来自 astro.build 的远程图像进行优化：

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

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

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

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" />

使用 CMS 或 CDN 中的图像

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

或者，CDN 可以提供自己的 SDK，以便更轻松地集成到 Astro 项目中。例如，Cloudinary 支持 Astro SDK，它允许你轻松地使用其 CldImage 组件来放入图像；又或者是 Node.js SDK，它可以生成 URL 以与 Node.js 环境中的 <img> 标签一起使用。

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

Markdown 文件中的图像

在 .md 文件中使用标准的 Markdown ![alt](src) 语法。这个语法可以与 Astro 的图像服务 API 一起使用，来优化你在 src/ 目录下的本地图像和远程图像。public/ 目录下的本地图像不会被优化。

# 我的 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 中的本地图像。

在 .md 文件中，<Image /> 和 <Picture /> 组件不可用。如果你需要对图像属性做更多的控制，我们建议使用 Astro 的 MDX 集成来添加对 .mdx 文件格式的支持。MDX 提供其他 MDX 中可用的图像选项，其中还包括通过 Markdown 语法来使用组件。

MDX 文件中的图像

你可以通过导入组件和图像在你的 .mdx 文件中使用 Astro 的 <Image /> 和 <Picture />组件。使用它们就像在 .astro 文件中使用一样。还支持使用 JSX <img /> 标签来展示不需要处理的图像，导入图像的方式与 HTML <img> 标签相同。

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

---
title: 我的页面标题
---
import { Image } from 'astro:assets';
import rocket from '../assets/rocket.png';

# 我的 MDX 页面

// 存储在同一文件夹中的本地图像
![太空中的火箭飞船](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 /> 和 <Picture /> 组件的完整 API 参考。

内容集合中的图像

内容集合中的图像将会按照你所使用的文件类型，以与 Markdown 和 MDX 中相同的方式处理。

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

---
title: "我的第一篇博客文章"
cover: "./firstpostcover.jpeg" # 将解析为 "src/content/blog/firstblogcover.jpeg"
coverAlt: "一张山脉后面的日落照片。"
---

这是一篇博客文章。

内容集合 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 传递给 <Image/>、<img> 或 getImage()。

下面的示例显示了一个博客索引页面，该页面从上面的模式中呈现了每篇博客文章的封面照片和标题：

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

框架组件中的图像

与任何其他 Astro 组件一样，<Image /> 组件在 UI 框架组件内不可用。

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

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

你还可以使用框架自己的图像语法来渲染图像（例如，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="繁星点点的夜空。" />

传递 Image 组件

<Image /> 组件，就像任何其他 Astro 组件一样，对 UI 框架组件不可用。

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

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

<ReactComponent>
  <Image src={stars} alt="繁星点点的夜空。" />
</ReactComponent>

使用 `getImage()` 生成图像

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

请参阅 getImage() 参考以了解更多信息。

相关操作指南： 构建自定义图像组件

替代文本

不是所有用户都能以相同的方式看到图像，因此在使用图像时，无障碍性尤为重要。使用 alt 属性为图像提供描述性的 alt 文本。

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

如果图像仅仅是装饰性的（即不会对页面的理解有所贡献），请设置 alt="" 以便屏幕阅读器和其他辅助技术知道忽略该图像。

默认图像服务

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

配置 no-op 透传服务

如果你的适配器不支持 Astro 内置的 Sharp 图片优化（如 Deno、Cloudflare），你可以配置一个 no-op 图像服务来使你可以使用 <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 标头允许，图像将被缓存，并且将被使用，直到它们不再 fresh。

重新验证

添加于： astro@5.1.0

重新验证通过检查远程服务器之前缓存的过期图像是否有效来减少带宽使用和构建时间。如果服务器指示图像仍然是有效（fresh）的，则重新使用缓存的版本，否则重新下载图像。

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

社区集成

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

贡献社区赞助

图像

在哪里存储图像

src/ vs public/

远程图像

.astro 文件中的图像

使用 <Image /> 组件显示优化后的图像

使用 <Picture /> 组件创建响应式图像

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

public/ 中的图像

远程图像

选择 <Image /> 还是 <img>

设置默认值

授权远程图像

SVG 组件

SVG 组件属性

使用 CMS 或 CDN 中的图像

Markdown 文件中的图像

MDX 文件中的图像

内容集合中的图像

框架组件中的图像

传递 Image 组件

使用 getImage() 生成图像

替代文本

默认图像服务

配置 no-op 透传服务

资源缓存

远程图像

重新验证

社区集成

`src/` vs `public/`

`.astro` 文件中的图像

使用 `<Image />` 组件显示优化后的图像

使用 `<Picture />` 组件创建响应式图像

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

`public/` 中的图像

选择 `<Image />` 还是 `<img>`

使用 `getImage()` 生成图像