官方插件

gatsby-plugin-image

手动添加响应式图片并保持高评分的性能可能很困难。Gatsby Image 插件为您处理了生成多种尺寸和格式图片的繁琐工作！

有关所有配置选项的完整文档，请参阅 Gatsby Image Plugin 参考指南

安装

安装 gatsby-plugin-image 和 gatsby-plugin-sharp。如果您使用静态图片，请另外安装 gatsby-source-filesystem；如果您使用动态图片，请安装 gatsby-transformer-sharp。

npm install gatsby-plugin-image gatsby-plugin-sharp gatsby-source-filesystem gatsby-transformer-sharp

将插件添加到您的 gatsby-config.js 文件中

module.exports = {
  plugins: [
    `gatsby-plugin-image`,
    `gatsby-plugin-sharp`,
    `gatsby-transformer-sharp`, // Needed for dynamic images
  ],
}

使用 Gatsby Image 组件

决定使用哪个组件

Gatsby Image 插件包含两个图片组件：一个用于静态图片，一个用于动态图片。决定您需要哪一个的有效方法是问自己：“当组件或模板使用时，这张图片是否每次都相同？”如果每次都相同，则使用 StaticImage。如果会改变，无论是通过 CMS 传来的数据，还是每次使用组件时传递给组件的不同值，那么它就是动态图片，您应该使用 GatsbyImage 组件。

静态图片

如果您使用的是每次使用组件时都相同的图片，例如 Logo 或首页的英雄图，则可以使用 StaticImage 组件。该图片可以是项目中的本地文件，也可以是远程服务器上的图片。任何远程图片都会在构建时下载并调整大小。

将图片添加到您的项目中。

如果您使用的是本地图片，请将其复制到项目中。例如 src/images 文件夹是一个不错的选择。
将 StaticImage 组件添加到您的模板中。

导入组件，然后设置 src 属性以指向您之前添加的图片。路径相对于源文件本身。如果您的组件文件是 src/components/dino.js，则像这样加载图片：
```
import { StaticImage } from "gatsby-plugin-image"

export function Dino() {
  return <StaticImage src="../images/dino.png" alt="A dinosaur" />
}
```
如果您使用的是远程图片，请在 src 属性中传递图片 URL
```
import { StaticImage } from "gatsby-plugin-image"

export function Kitten() {
  return <StaticImage src="https://placekitten.com/800/600" alt="A kitten" />
}
```
当您构建站点时，StaticImage 组件将从您的文件系统或远程 URL 加载图片，并生成支持响应式图片所需的所有尺寸和格式。

由于图片是在构建时加载的，因此您不能将文件名作为 prop 传递，也不能在组件外部生成它。它应该是一个静态字符串，或组件范围内的局部变量。

重要提示：远程图片将在构建时下载并调整大小。如果图片在其他服务器上发生更改，您的站点上的图片直到重新构建后才会被更新。
配置图片。

您可以通过将属性传递给 <StaticImage /> 组件来配置图片。您可以更改大小和布局，以及诸如懒加载时使用的占位符类型等设置。还提供高级图片处理选项。您可以在 API 文档中找到完整选项列表。
```
import { StaticImage } from "gatsby-plugin-image"

export function Dino() {
  return (
    <StaticImage
      src="../images/dino.png"
      alt="A dinosaur"
      placeholder="blurred"
      layout="fixed"
      width={200}
      height={200}
    />
  )
}
```
此组件渲染一张 200x200 像素的恐龙图片。加载前，它将有一个模糊的、低分辨率的占位符。它使用 "fixed" 布局，这意味着图片不会随着其容器缩放。

使用 `StaticImage` 的限制

在将属性传递给 StaticImage 的方式上有一些技术限制。最重要的是，您不能使用任何父组件的属性。有关更多信息，请参阅 Gatsby Image 插件参考指南。如果您发现自己希望能够使用父组件传递的属性作为图片的 src，那么很可能您应该使用动态图片。

动态图片

如果您需要动态图片（例如，它们来自 CMS），则可以通过 GraphQL 加载它们，并使用 GatsbyImage 组件进行显示。

将图片添加到您的页面查询中。

任何包含图片的 GraphQL File 对象都会有一个 childImageSharp 字段，您可以使用它来查询图片数据。确切的数据结构将根据您的数据源而有所不同，但语法如下：
```
query {
  blogPost(id: { eq: $Id }) {
    title
    body
    avatar {
      childImageSharp {
        gatsbyImageData(width: 200)
      }
    }
  }
}
```

配置您的图片。

有关所有配置选项，请参阅 Gatsby Image 插件参考指南。

您可以通过向 gatsbyImageData 解析器传递参数来配置图片。您可以更改大小和布局，以及诸如懒加载时使用的占位符类型等设置。还提供高级图片处理选项。您可以在 API 文档中找到完整选项列表。

query {
  blogPost(id: { eq: $Id }) {
    title
    body
    author
    avatar {
      childImageSharp {
        gatsbyImageData(
          width: 200
          placeholder: BLURRED
          formats: [AUTO, WEBP, AVIF]
        )
      }
    }
  }
}

显示图片。

然后，您可以使用 GatsbyImage 组件在页面上显示图片。getImage() 函数是一个可选的辅助函数，可以使您的代码更易读。它接受一个 File 对象并返回 file.childImageSharp.gatsbyImageData，然后可以将其传递给 GatsbyImage 组件。

import { graphql } from "gatsby"
import { GatsbyImage, getImage } from "gatsby-plugin-image"

function BlogPost({ data }) {
  const image = getImage(data.blogPost.avatar)
  return (
    <section>
      <h2>{data.blogPost.title}</h2>
      <GatsbyImage image={image} alt={data.blogPost.author} />
      <p>{data.blogPost.body}</p>
    </section>
  )
}

export const pageQuery = graphql`
  query {
    blogPost(id: { eq: $Id }) {
      title
      body
      author
      avatar {
        childImageSharp {
          gatsbyImageData(
            width: 200
            placeholder: BLURRED
            formats: [AUTO, WEBP, AVIF]
          )
        }
      }
    }
  }
`

有关完整的 API，请参阅 Gatsby Image 插件参考指南。

自定义默认选项

您可能会发现，在大多数 GatsbyImage 和 StaticImage 实例中使用相同的选项（如 placeholder、formats 等）。您可以使用 gatsby-plugin-sharp 自定义默认选项。

以下配置描述了可以自定义的选项及其默认值

gatsby-config.js

module.exports = {
  plugins: [
    {
      resolve: `gatsby-plugin-sharp`,
      options: {
        defaults: {
          formats: [`auto`, `webp`],
          placeholder: `dominantColor`,
          quality: 50,
          breakpoints: [750, 1080, 1366, 1920],
          backgroundColor: `transparent`,
          tracedSVGOptions: {},
          blurredOptions: {},
          jpgOptions: {},
          pngOptions: {},
          webpOptions: {},
          avifOptions: {},
        }
      }
    },
    `gatsby-transformer-sharp`,
    `gatsby-plugin-image`,
  ],
}

迁移

主文章：从 gatsby-image 迁移到 gatsby-plugin-image

如果您的站点使用了旧的 gatsby-image 组件，您可以使用 codemod 来帮助您迁移到新的 Gatsby Image 组件。这可以更新大多数站点的代码。要使用 codemod，请在您的站点根目录运行此命令：

npx gatsby-codemods gatsby-plugin-image

这将把所有 GraphQL 查询和组件转换为使用新的插件。有关更多详细信息，请参阅迁移指南。