图片
Astro 为你提供了多种在站点上使用图片的方法,无论它们是存储在项目本地、从外部 URL 链接还是在 CMS 或 CDN 中管理!
¥Astro provides several ways for you to use images on your site, whether they are stored locally inside your project, linked to from an external URL, or managed in a CMS or CDN!
<Image />
and <Picture />
components.
存储图片的位置
标题部分 存储图片的位置¥Where to store images
src/
与 public/
标题部分 src/ 与 public/¥src/
vs public/
我们建议尽可能将本地图片保留在 src/
中,以便 Astro 可以对其进行转换、优化和打包。/public
目录中的文件始终按原样提供或复制到构建文件夹中,不进行任何处理。
¥We recommend that local images are kept in src/
when possible so that Astro can transform, optimize and bundle them. Files in the /public
directory are always served or copied into the build folder as-is, with no processing.
你存储在 src/
中的本地图片可供项目中的所有文件使用:.astro
、.md
、.mdx
、.mdoc
等 UI 框架。图片可以存储在任何文件夹中,包括与内容一起存储。
¥Your local images stored in src/
can be used by all files in your project: .astro
, .md
, .mdx
, .mdoc
, and other UI frameworks. Images can be stored in any folder, including alongside your content.
如果你想避免任何处理或拥有指向图片的直接公共链接,请将图片存储在 public/
文件夹中。
¥Store your images in the public/
folder if you want to avoid any processing or to have a direct public link to them.
远程图片
标题部分 远程图片¥Remote images
你还可以选择在 内容管理系统 (CMS) 或 数字资源管理 (DAM) 平台中远程存储图片。Astro 可以使用 API 远程获取你的数据或从完整 URL 路径显示图片。
¥You can also choose to store your images remotely, in a content management system (CMS) or digital asset management (DAM) platform. Astro can fetch your data remotely using APIs or display images from their full URL path.
为了在处理外部源时获得额外的保护,Astro 的图片组件和助手函数将仅处理(例如优化、转换)来自 配置中指定的授权图片源 的图片。来自其他来源的远程图片将不经处理显示。
¥For extra protection when dealing with external sources, Astro’s image components and helper function will only process (e.g. optimize, transform) images from authorized image sources specified in your configuration. Remote images from other sources will be displayed with no processing.
.astro
文件中的图片
标题部分 .astro 文件中的图片¥Images in .astro
files
在 .astro
文件中,必须从其相对路径导入本地图片。此导入为你的图片提供 src
值。
¥In .astro
files, a local image must be imported from its relative path. This import provides the src
value for your image.
远程和 public/
图片不需要导入,而是需要 src
的 URL(完整路径或你网站上的相对路径)。
¥Remote and public/
images do not require importing, and instead require a URL (full, or relative path on your site) for src
.
导入并使用 Astro 的原生 <Image />
和 <Picture />
组件来优化图片。Astro 语法还支持 直接编写 HTML <img>
标签,它跳过了图片处理。
¥Import and use Astro’s native <Image />
and <Picture />
components for optimized images. Astro syntax also supports writing an HTML <img>
tag directly, which skips image processing.
<Image />
and <Picture />
components.
使用 <Image />
显示优化图片组件
标题部分 使用 <Image /> 显示优化图片组件¥Display optimized images with the <Image />
component
使用内置的 <Image />
Astro 组件显示优化版本:
¥Use the built-in <Image />
Astro component to display optimized versions of:
-
位于
src/
文件夹中的本地图片 -
来自授权来源的 配置远程图片
<Image />
可以转换本地或授权的远程图片的尺寸、文件类型和质量,以控制显示的图片。生成的 <img>
标签包括 alt
、loading
和 decoding
属性,并推断图片尺寸以避免累积布局偏移 (CLS)。
¥<Image />
can transform a local or authorized remote image’s dimensions, file type, and quality for control over your displayed image. The resulting <img>
tag includes alt
, loading
, and decoding
attributes and infers image dimensions to avoid Cumulative Layout Shift (CLS).
<Image />
组件接受 几种组件属性 以及 HTML <img>
标记接受的任何属性。
¥The <Image />
component accepts several component properties as well as any attributes accepted by the HTML <img>
tag.
以下示例为图片组件提供 class
,该组件将应用于最终的 <img>
元素。
¥The following example provides a class
to the image component which will apply to the final <img>
element.
使用 <Picture />
组件创建响应式图片
标题部分 使用 <Picture /> 组件创建响应式图片¥Create responsive images with the <Picture />
component
Added in:
astro@3.3.0
使用内置的 <Picture />
Astro 组件显示具有多种格式和/或尺寸的响应式图片。
¥Use the built-in <Picture />
Astro component to display a responsive image with multiple formats and/or sizes.
<Picture />
component properties in the astro:assets
reference.
使用 HTML <img>
标签显示未处理的图片
标题部分 使用 HTML <img> 标签显示未处理的图片¥Display unprocessed images with the HTML <img>
tag
Astro 模板语法 还支持直接写入 <img>
标签,并完全控制其最终输出。这些图片将不会被处理和优化。它接受所有 HTML <img>
标记属性,唯一必需的属性是 src
。
¥The Astro template syntax also supports writing an <img>
tag directly, with full control over its final output. These images will not be processed and optimized. It accepts all HTML <img>
tag properties, and the only required property is src
.
必须从现有 .astro
文件的相对路径导入本地图片,或者你可以配置和使用 import alias。然后,你可以访问图片的 src
和其他属性以在 <img>
标记中使用。
¥Local images must be imported from the relative path from the existing .astro
file, or you can configure and use an import alias. Then, you can access the image’s src
and other properties to use in the <img>
tag.
导入的图片资源与以下签名匹配:
¥Imported image assets match the following signature:
以下示例使用图片自己的 height
和 width
属性来避免累积布局偏移 (CLS) 并改进核心 Web 生命力:
¥The following example uses the image’s own height
and width
properties to avoid Cumulative Layout Shift (CLS) and improve Core Web Vitals:
public/
中的图片
标题部分 public/ 中的图片¥Images in public/
对于位于 public/
内的图片,请使用相对于公共文件夹的图片文件路径作为 src
值:
¥For images located within public/
use the image’s file path relative to the public folder as the src
value:
远程图片
标题部分 远程图片¥Remote images
对于远程图片,请使用图片的完整 URL 作为 src
值:
¥For remote images, use the image’s full URL as the src
value:
选择 <Image />
与 <img>
标题部分 选择 <Image /> 与 <img>¥Choosing <Image />
vs <img>
<Image />
组件会优化你的图片并根据原始纵横比推断宽度和高度(对于它可以处理的图片)以避免 CLS。这是在尽可能的情况下在 .astro
文件中使用图片的首选方式。
¥The <Image />
component optimizes your image and infers width and height (for images it can process) based on the original aspect ratio to avoid CLS. It is the preferred way to use images in .astro
files whenever possible.
当无法使用 <Image />
组件时,请使用 HTML <img>
元素,例如:
¥Use the HTML <img>
element when you cannot use the <Image />
component, for example:
-
对于不支持的图片格式
-
当你不希望 Astro 优化你的图片时
-
在客户端动态访问和更改
src
属性
设置默认值
标题部分 设置默认值¥Setting Default Values
目前,无法为所有 <Image />
或 <Picture/>
组件指定默认值。应在每个单独的组件上设置必需的属性。
¥Currently, there is no way to specify default values for all <Image />
or <Picture/>
components. Required attributes should be set on each individual component.
作为替代方案,你可以将这些组件封装在另一个 Astro 组件中以供重用。例如,你可以为博客文章图片创建一个组件,该组件接收属性作为 props 并将一致的样式应用于每个图片:
¥As an alternative, you can wrap these components in another Astro component for reuse. For example, you could create a component for your blog post images that receives attributes as props and applies consistent styles to each image:
授权远程图片
标题部分 授权远程图片¥Authorizing remote images
你可以使用 image.domains
和 image.remotePatterns
配置授权图片源 URL 域和图片优化模式的列表。此配置是额外的安全层,可以在显示来自外部源的图片时保护你的站点。
¥You can configure lists of authorized image source URL domains and patterns for image optimization using image.domains
and image.remotePatterns
. This configuration is an extra layer of safety to protect your site when showing images from an external source.
来自其他来源的远程图片不会被优化,但对这些图片使用 <Image />
组件将防止累积布局偏移 (CLS)。
¥Remote images from other sources will not be optimized, but using the <Image />
component for these images will prevent Cumulative Layout Shift (CLS).
例如,以下配置将仅允许优化来自 astro.build
的远程图片:
¥For example, the following configuration will only allow remote images from astro.build
to be optimized:
以下配置仅允许来自 HTTPS 主机的远程图片:
¥The following configuration will only allow remote images from HTTPS hosts:
使用来自 CMS 或 CDN 的图片
标题部分 使用来自 CMS 或 CDN 的图片¥Using Images from a CMS or CDN
图片 CDN 与 所有 Astro 图像选项 配合使用。使用图片的完整 URL 作为 <Image />
组件、<img>
标签或 Markdown 表示法中的 src
属性。对于远程图片的图片优化,还有 配置你的授权域或 URL 模式。
¥Image CDNs work with all Astro image options. Use an image’s full URL as the src
attribute in the <Image />
component, an <img>
tag, or in Markdown notation. For image optimization with remote images, also configure your authorized domains or URL patterns.
或者,CDN 可以提供自己的 SDK,以便更轻松地集成到 Astro 项目中。例如,Cloudinary 支持 Astro SDK,它允许你使用其 CldImage
组件轻松插入图片,或者支持 Node.js SDK,它可以生成 URL 以在 Node.js 环境中与 <img>
标签一起使用。
¥Alternatively, the CDN may provide its own SDKs to more easily integrate in an Astro project. For example, Cloudinary supports an Astro SDK which allows you to easily drop in images with their CldImage
component or a Node.js SDK that can generate URLs to use with an <img>
tag in a Node.js environment.
<Image />
and <Picture />
components.
Markdown 文件中的图片
标题部分 Markdown 文件中的图片¥Images in Markdown files
在 .md
文件中使用标准 Markdown ![alt](src)
语法。此语法与 Astro 的 图片服务 API 配合使用,以优化存储在 src/
中的本地图片。远程图片和存储在 public/
文件夹中的图片未经过优化。
¥Use standard Markdown ![alt](src)
syntax in your .md
files. This syntax works with Astro’s Image Service API to optimize your local images stored in src/
. Remote images and images stored in the public/
folder are not optimized.
<img>
标签不支持本地图片,<Image />
和 <Picture />
组件在 .md
文件中不可用。
¥The <img>
tag is not supported for local images, and the <Image />
and <Picture />
components are unavailable in .md
files.
如果你需要更好地控制图片属性,我们建议使用 Astro 的 MDX 集成 来添加对 .mdx
文件格式的支持。MDX 允许向 Markdown 添加组件,并且还有其他 MDX 中可用的图片选项。
¥If you require more control over your image attributes, we recommend using Astro’s MDX integration to add support for.mdx
file format. MDX allows adding components to Markdown and there are additional image options available in MDX.
MDX 文件中的图片
标题部分 MDX 文件中的图片¥Images in MDX files
你可以通过导入组件和图片在 .mdx
文件中使用 Astro 的 <Image />
和 <Picture />
组件。像 used in .astro
files. The JSX <img />
tag is also supported for unprocessed images and uses the same image import as the HTML <img>
tag 一样使用它们。
¥You can use Astro’s <Image />
and <Picture />
components in your .mdx
files by importing both the component and your image. Use them just as they are used in .astro
files. The JSX <img />
tag is also supported for unprocessed images and uses the same image import as the HTML <img>
tag.
此外,还支持 标准 Markdown ![alt](src)
语法,无需导入。
¥Additionally, there is support for standard Markdown ![alt](src)
syntax with no import required.
<Image />
and <Picture />
components.
内容集合中的图片
标题部分 内容集合中的图片¥Images in content collections
内容集合中的图片将以与 Markdown 和 MDX 中相同的方式处理,具体取决于你使用的文件类型。
¥Images in content collections will be processed the same way they are in Markdown and MDX depending on which file type you are using.
此外,你可以在前言中使用相对于当前文件夹的路径为内容集合条目(例如博客文章的封面图片)声明关联图片:
¥Additionally, you can declare an associated image for a content collections entry, such as a blog post’s cover image, in your frontmatter using its path relative to the current folder:
内容集合架构的 image
助手允许你验证和导入图片。
¥The image
helper for the content collections schema lets you validate and import the image.
图片将被导入并转换为元数据,允许你将其作为 src
到 <Image/>
、<img>
或 getImage()
传递。
¥The image will be imported and transformed into metadata, allowing you to pass it as a src
to <Image/>
, <img>
, or getImage()
.
下面的示例显示了一个博客索引页面,该页面根据上面的架构渲染每个博客文章的封面照片和标题:
¥The example below shows a blog index page that renders the cover photo and title of each blog post from the schema above:
UI 框架组件中的图片
标题部分 UI 框架组件中的图片¥Images in UI framework components
<Image />
组件与任何其他 Astro 组件一样,在 UI 框架组件内不可用。
¥The <Image />
component, like any other Astro component, is unavailable inside UI framework components.
但是,你可以将 <Image />
生成的静态内容传递给 .astro
文件 作为子项 内的框架组件或使用 命名为 <slot/>
:
¥But, you can pass the static content generated by <Image />
to a framework component inside a .astro
file as children or using a named <slot/>
:
你还可以使用框架自己的图片语法来渲染图片(例如 JSX 中的 <img />
、Svelte 中的 <img>
)。
¥You can also use the framework’s own image syntax to render an image (e.g. <img />
in JSX, <img>
in Svelte).
Local images must first be imported 访问其图片属性,例如 src
。
¥Local images must first be imported to access their image properties such as src
.
使用 getImage()
生成图片
标题部分 使用 getImage() 生成图片¥Generating images with getImage()
getImage()
函数旨在生成要在其他地方使用的图片,而不是直接在 HTML 中使用,例如在 API 路由 中。当你需要 <Picture>
和 <Image>
组件当前不支持的选项时,你可以使用 getImage()
函数创建自己的自定义 <Image />
组件。
¥The getImage()
function is intended for generating images destined to be used somewhere else than directly in HTML, for example in an API Route. When you need options that the <Picture>
and <Image>
components do not currently support, you can use the getImage()
function to create your own custom <Image />
component.
getImage()
reference.
替代文本
标题部分 替代文本¥Alt Text
并非所有用户都能以相同的方式查看图片,因此在使用图片时可访问性是一个特别重要的问题。使用 alt
属性为图片提供 描述性替代文本。
¥Not all users can see images in the same way, so accessibility is an especially important concern when using images. Use the alt
attribute to provide descriptive alt text for images.
此属性对于 <Image />
和 <Picture />
组件都是必需的。如果没有提供替代文本,将提供有用的错误消息,提醒你包含 alt
属性。
¥This attribute is required for both the <Image />
and <Picture />
components. If no alt text is provided, a helpful error message will be provided reminding you to include the alt
attribute.
如果图片只是装饰性的(即无助于理解页面),请设置 alt=""
以便屏幕阅读器知道忽略该图片。
¥If the image is merely decorative (i.e. doesn’t contribute to the understanding of the page), set alt=""
so that screen readers know to ignore the image.
默认图片服务
标题部分 默认图片服务¥Default image service
Sharp 是 astro:assets
使用的默认影像服务。你可以使用 image.service
选项进一步配置图片服务。
¥Sharp is the default image service used for astro:assets
. You can further configure the image service using the image.service
option.
配置无操作直通服务
标题部分 配置无操作直通服务¥Configure no-op passthrough service
如果你的 adapter 不支持 Astro 内置的 Sharp 图片优化(例如 Deno、Cloudflare),你可以配置无操作图片服务以允许你使用 <Image />
和 <Picture />
组件。请注意,Astro 在这些环境中不会执行任何图片转换和处理。但是,你仍然可以享受使用 astro:assets
的其他好处,包括无累积布局偏移 (CLS)、强制的 alt
属性以及一致的创作体验。
¥If your adapter does not support Astro’s built-in Sharp image optimization (e.g. Deno, Cloudflare), you can configure a no-op image service to allow you to use the <Image />
and <Picture />
components. Note that Astro does not perform any image transformation and processing in these environments. However, you can still enjoy the other benefits of using astro:assets
, including no Cumulative Layout Shift (CLS), the enforced alt
attribute, and a consistent authoring experience.
配置 passthroughImageService()
以避免 Sharp 图片处理:
¥Configure the passthroughImageService()
to avoid Sharp image processing:
资源缓存
标题部分 资源缓存¥Asset Caching
Astro 在为本地和 来自授权来源的远程图片 构建站点期间将处理后的图片资源存储在缓存目录中。通过在构建之间保留缓存目录,可以重用已处理的资源,从而缩短构建时间并减少带宽使用。
¥Astro stores processed image assets in a cache directory during site builds for both local and remote images from authorized sources. By preserving the cache directory between builds, processed assets are reused, improving build time and bandwidth usage.
默认缓存目录是 ./node_modules/.astro
,但可以使用 cacheDir
配置设置进行更改。
¥The default cache directory is ./node_modules/.astro
, however this can be changed using the cacheDir
configuration setting.
远程图片
标题部分 远程图片¥Remote Images
资源缓存中的远程图片基于 HTTP 缓存 进行管理,并尊重远程服务器返回的 Cache-Control 标头。如果 Cache-Control 标头允许,则将缓存图片,并将一直使用到它们不再是 fresh 为止。
¥Remote images in the asset cache are managed based on HTTP Caching, and respect the Cache-Control header returned by the remote server. Images are cached if the Cache-Control header allows, and will be used until they are no longer fresh.
重新验证
标题部分 重新验证¥Revalidation
Added in:
astro@5.1.0
新
重新验证 通过与远程服务器检查过期的缓存图片是否仍然是最新的来减少带宽使用量和构建时间。如果服务器指示图片仍是最新的,则重新使用缓存版本,否则将重新下载图片。
¥Revalidation reduces bandwidth usage and build time by checking with the remote server whether an expired cached image is still up-to-date. If the server indicates that the image is still fresh, the cached version is reused, otherwise the image is redownloaded.
重新验证要求远程服务器在其响应中发送 Last-Modified 和/或 Etag(实体标签) 标头。此功能适用于支持 If-Modified-Since 和 If-None-Match 标头的远程服务器。
¥Revalidation requires that the remote server send Last-Modified and/or Etag (entity tag) headers with its responses. This feature is available for remote servers that support the If-Modified-Since and If-None-Match headers.
社区整合
标题部分 社区整合¥Community Integrations
有多个第三方 社区形象整合 用于优化和处理 Astro 项目中的图片。
¥There are several third-party community image integrations for optimizing and working with images in your Astro project.
Learn