使用 Gatsby 从 Etsy 商城拉取商品数据:gatsby-source-etsy 插件实战指南

原创2026-09-19 18:58:311,951 阅读
文章标签:前端静态站点Web框架

使用 Gatsby 从 Etsy 商城拉取商品数据:gatsby-source-etsy 插件实战指南

本指南聚焦于将 Etsy 店铺中的精选商品(featured listings)与图片作为数据源引入 Gatsby 站点。全文将带你完成从注册 Etsy 应用获取 API Key,到在 gatsby-config.js 中配置插件,再到通过 GraphQL 查询并在页面组件中渲染商品卡片的完整链路,并深入讲解 Etsy 插件背后的数据建模与 Gatsby 图片处理原理,让你既能照做落地,也能知其所以然。

为什么要把 Etsy 当作 Gatsby 的数据源

Etsy 是一个专注于手工制品、复古与定制商品买卖的在线市场,长期是创意创业者的聚集地。作为数据源,它天然具备两类价值:一是店铺里的商品数据(标题、价格、描述、链接)本身结构清晰、适合建模;二是商品图片可以直接复用 Gatsby 的图片处理管线,获得响应式、懒加载等开箱即用的优化能力。

在 Gatsby 中,几乎所有内容源(CMS、电商平台、数据库)都是通过 source 插件接入的:插件在构建期拉取外部数据,把每条记录转换为 GraphQL 数据层中的一个节点(node),随后你就可以用 GraphQL 查询这些节点并渲染到页面上。Gatsby 官网文档中关于 source 插件的说明 以及仓库内的 examples/creating-source-plugins/README.md(一个展示 API、站点与 source 插件三者如何协作的完整示例)都印证了这一工作模式:gatsby-source-etsy 扮演的正是“从 Etsy API 拉数据、写节点”的那一环。

前置条件

开始之前,请确认你已具备两样东西:

  1. 一个可运行的 Gatsby 站点。如果还没有,可以参考 Quick Start 指南 在几分钟内新建一个站点;
  2. 一个已开通的 Etsy 店铺。本指南假设店铺中已有商品(listing),插件主要拉取的是其中的“精选商品”(featured listings)。

需要特别提醒的是:Etsy 官方期望开发者使用真实数据来测试 API。这意味着即使你在开发这个站点,店铺和商品也始终处于公开可见状态。如果你已经是活跃的 Etsy 卖家,这通常不会改变你的日常流程;但如果你是新建店铺做测试,务必留意 Etsy 的 API 测试政策,避免违规。

获取 API Key:两步准备

要让插件能够访问 Etsy API,你需要一个 API Key。获取流程如下:

  1. 开启两步验证:Etsy 要求账号启用双因素认证(two-factor authentication)。如果你尚未开启,在注册新应用时系统会引导你完成;
  2. 注册应用:前往 Etsy 开发者平台的注册页面,尽可能完整地填写应用信息,阅读并接受 Etsy 的条款后创建应用。

创建完成后,你会拿到一串 API Key(api_key)。这一步完成后,我们离“把 Etsy 变成数据源”只差一个插件。

安装与配置 gatsby-source-etsy 插件

安装插件

gatsby-source-etsy 是社区开发的 Gatsby 官方插件生态中的一员(在文档中被列为可用插件),用于把店铺的精选商品及图片拉入 Gatsby 站点。安装命令:

npm install gatsby-source-etsy

配置插件

安装完成后,需要把插件、API Key 和店铺 ID 添加到 gatsby-config.js:

plugins: [
  {
    resolve: "gatsby-source-etsy",
    options: {
      // highlight-start
      api_key: "your api key here",
      shop_id: "your shop id or shop name here",
      // highlight-end
      language: "en", // optional
    },
  },
],

关于 shop_id 的一个重要细节

文档特别指出:找店铺 ID 这件事很容易让人困惑。虽然每个 Etsy 店铺都有一个数字形式的 ID(shop_id),但你在请求 Etsy API 时并不必须使用它——如果你不知道店铺 ID,可以直接用店铺名称(shop name)作为唯一标识符。Etsy 的 API 允许通过店铺名来定位店铺,因此配置项里写店铺名同样可行。

language 是可选配置,用于指定返回内容(如商品描述)的语言,默认示例为 "en"。你可以根据自己店铺的受众语言调整取值。

如果你希望深入了解 source 插件的整体工作方式(数据如何被拉取、节点如何创建、如何通过 gatsby-config.js 传入 options),仓库内的 examples/creating-source-plugins 提供了一个完整的“API + source 插件 + 站点”三方协作示例,可以作为理解 gatsby-source-etsy 内部机制的最佳参照。

用 GraphiQL 验证数据查询

配置完成并保存后,在项目根目录运行:

gatsby develop

启动本地开发服务器后,打开 GraphiQL(Gatsby 内置的 GraphQL 集成开发环境,访问地址为 http://localhost:8000/___graphql)。关于 GraphiQL 的详细用法,可参考 在 GraphiQL 中运行查询:左侧编写查询,右侧展示结果,支持语法高亮、自动补全与内置文档浏览器。

进入 GraphiQL 后,你可以输入以下查询,获取店铺精选商品的总数以及每件商品的价格、标题和描述:

allFeaturedEtsyListing {
  totalCount
    nodes {
      price
      title
      description
    }
  }
  • allFeaturedEtsyListing:插件创建的“精选商品”集合类型。Gatsby 的惯例是,为每种节点类型同时提供单条查询(如 featuredEtsyListing)和集合查询(allXxx),后者支持 totalCount、分页与过滤参数,详见 GraphQL 参考文档 中的 totalCount 与过滤相关章节;
  • totalCount:返回符合条件的节点总数,适合用来快速确认数据是否成功拉取。

一个容易踩坑的点:插件拉取的是精选商品(featured listings),如果你的店铺里没有任何精选商品,这条查询会返回空结果。要设置精选商品,请进入 Shop Manager(店铺管理后台),在“Sales Channels”(销售渠道)下选择你的 Etsy 店铺,找到编辑或启用精选商品的选项进行设置。设置完成后重启 gatsby develop 即可看到数据。

在页面中展示 Etsy 商品列表

验证查询可用之后,就可以把数据真正渲染到页面上了。核心思路是:在页面或组件中编写 GraphQL 查询,把返回的数据通过 props 传入组件进行渲染。

查询商品与图片

下面的查询获取每件精选商品的 id、标题、价格、URL、描述 以及一张经过 Gatsby 处理的图片:

allFeaturedEtsyListing {
  nodes {
    id
    title
    price
    url
    description
    childEtsyListingImage {
      childFile {
        childImageSharp {
          fixed(width: 400, height: 400) {
            ...GatsbyImageSharpFixed
          }
        }
      }
    }
  }
}

这条查询透露了 Etsy 插件数据建模的两个关键信息:

  1. 节点关系:插件为每件商品创建 FeaturedEtsyListing 节点,并让商品节点与图片节点建立父子关系——通过 childEtsyListingImage 可以访问图片节点,再通过 childFile 访问到图片对应的文件节点(File);
  2. 接入 Gatsby 图片管线:childFile.childImageSharp.fixed(width: 400, height: 400) 说明插件生成的图片文件节点与 gatsby-plugin-sharp 的 childImageSharp 节点相连,因此可以复用 Gatsby Image API 的全部能力——fixed 会按设定尺寸生成 1x、1.5x、2x 等多分辨率版本,...GatsbyImageSharpFixed 则是一个片段(fragment),一条语句即可取回 src、srcSet、base64 等所有必要字段。

这也解释了为什么一个 Etsy 店铺需要同时安装 gatsby-source-etsy、gatsby-transformer-sharp、gatsby-plugin-sharp 与 gatsby-image:source 插件负责拉数据,transformer 与 sharp 负责把远程图片变成可优化的本地文件节点,gatsby-image 负责在 React 侧渲染优化后的图片。关于这套图片管线的底层架构,可参考 图片插件架构 中的说明。

渲染商品卡片组件

把上述查询放到页面查询(page query)中后,可以在 JSX 中这样遍历渲染:

{
  data.allFeaturedEtsyListing.nodes.map(item => (
    <section key={item.id}>
      <a href={item.url}>
        <h2>{item.title}</h2>
      </a>
      <Img fixed={item.childEtsyListingImage.childFile.childImageSharp.fixed} />
      <p>${item.price}</p>
      <p>{item.description}</p>
    </section>
  ))
}

要点说明:

  • 每件商品用 <section> 包裹,并以 item.id 作为 React 的 key;
  • 商品标题放在指向 item.url(Etsy 商品详情页)的链接内,点击即可跳转回 Etsy 完成购买;
  • 图片通过 gatsby-image 的 Img 组件渲染,传入查询得到的 fixed 数据,自动获得响应式与懒加载优化。

关于 alt 文本的一个可访问性考虑

注意示例中的 Img 组件没有传 alt 文本——这不是疏漏,而是有意为之:这张图片属于装饰性(presentational)图片,它与标题、描述并列展示,标题和描述已经把商品信息传达给用户了。如果再把同样的信息写进 alt 文本,对使用屏幕阅读器的用户反而是重复信息干扰。

不过在真实项目中,是否省略 alt 需要结合你的布局判断:如果图片承载了标题、描述之外的信息(比如商品细节特写),仍应补充描述性的 alt 文本。

补充:使用 gatsby-image 的进阶图片参数

当你把 childEtsyListingImage.childFile.childImageSharp.fixed 传给 Img 组件时,还可以通过查询参数微调图片行为。fixed 类型支持以下参数(默认值来自 Gatsby Image API):

参数 说明 默认值
width 图片宽度(像素) 400
height 图片高度(像素) 无
quality 图片质量 50

返回的数据包含 base64(占位图数据 URI)、aspectRatio、width、height、src、srcSet 等字段。若希望图片随容器宽度自适应,可使用 fluid 类型(maxWidth 默认 800),并搭配 ...GatsbyImageSharpFluid 片段。是否引入这些进阶用法,取决于你希望商品卡片采用固定尺寸还是流式布局。

保持两者优势:Etsy 卖 + Gatsby 站

如果熟悉 Etsy,你会了解平台在品牌化上的限制:各家店铺外观高度相似,这限制了店主发挥创意的空间;同时你也无法控制 Etsy 的平台政策。

但 Etsy 作为销售渠道的优势同样巨大——你在个性上的损失,换来的是可发现性(discoverability):

  • Etsy 的广告预算远超个人店主能负担的规模,流量红利可观;
  • Etsy 多年积累的用户信任,让买家会习惯性地直接去 Etsy 搜索手工或复古商品;
  • 你依然保有在 Etsy 上架、曝光、成交的完整权益。

用 Gatsby 自建站点,则可以“两全其美”:你完全掌控访客在自家网站上的体验,把流量导向自己飞快加载的站点(Gatsby 的构建期优化天然适合这类内容型页面);同时你的商品页面上不会出现竞品商品的推荐链接来分散顾客注意力。两条渠道并行——Etsy 负责被找到,Gatsby 站点负责被记住。

延伸阅读

登录后查看全文
gatsby