企业官网建设流程全解析

如何快速批量导入资产到Hygraph：Asset Upload端点与Bee-Queue队列实战教程

【免费下载链接】hygraph-examplesExample projects to help you get started with Hygraph项目地址: https://gitcode.com/gh_mirrors/hy/hygraph-examples

在 Hygraph 内容管理系统中，手动一张张上传图片和媒体文件效率极低。本文基于hygraph-examples示例仓库中的using-asset-upload案例，带你看懂如何用Asset Upload 端点从 URL 批量导入资产到 Hygraph，并借助Bee-Queue作业队列实现带自动重试的可靠批量导入，适合大规模数据迁移与资产同步场景 🚀

为什么批量导入资产需要消息队列？

很多新手第一次批量导入资产时，会写一个for循环直接循环请求，结果往往遇到：

• 网络抖动导致部分失败：一个 URL 404 就中断整批任务；
• 没有重试机制：临时超时就得人工补跑；
• 无进度感知：不知道哪些成功、哪些失败。

Bee-Queue 是一个轻量级的 Node.js 作业队列，天然支持任务级重试、退避策略和状态日志。官方示例正是用它来处理"大批量导入"这个推荐场景 👍

一键获取 Hygraph 资产批量导入示例

示例项目位于 using-asset-upload/ 目录，包含完整可运行的 Node.js 脚本：

克隆仓库并进入示例目录：

git clone https://gitcode.com/gh_mirrors/hy/hygraph-examples cd hygraph-examples/using-asset-upload

Asset Upload 端点：批量资产导入的核心

整个导入流程的关键，是向 Hygraph 的/upload端点发起一个带鉴权的 POST 请求。在 src/index.js 中的assetUpload函数可以看到完整实现，其要点只有三步：

1. 请求地址为${HYGRAPH_ENDPOINT}/upload；
2. 请求头携带Authorization: Bearer ${HYGRAPH_TOKEN}与表单编码类型；
3. 请求体只需一个url参数——Hygraph 会自动下载该 URL 的资源并存入你的项目资产库。

也就是说，你不需要在本地中转图片文件，只要资产有可公网访问的 URL，就能"指针式"批量入库 ✅

Bee-Queue 队列实战：重试与退避怎么配置？

批量导入最怕"跑一半失败"。示例在 src/index.js 中为每个资产 URL 创建一个独立作业，并做了两个关键配置：

• .retries(3)：单个作业失败后自动重试最多 3 次；
• .backoff('fixed', 5000)：每次重试间隔固定 5 秒，避免瞬时故障导致连环失败。

这意味着哪怕 1000 个 URL 中有几个临时 404 或超时，队列也会自动补跑，而不需要人工介入。

快速上手：3 步跑通批量导入

第 1 步：配置环境变量。复制示例的环境变量模板并填入你的 Hygraph 项目信息：

cp .env.sample .env

在.env中填写两项：HYGRAPH_TOKEN（管理 Token）和HYGRAPH_ENDPOINT（项目 API 地址）。

第 2 步：安装依赖。

npm install

第 3 步：执行导入。把资产清单文件作为命令行参数传入：

npm run start assets.json

其中 assets.json 就是一个简单的 URL 数组，想批量导入多少资产，就往里追加多少条记录即可。

如何看懂批量导入结果

脚本会实时输出三类日志，帮你精准定位每一个作业的状态：

• [PROCESSING]: 1—— 作业开始处理；
• [SUCCESS]: 2—— 资产导入成功；
• [RETRYING]: 3 (error)—— 正在自动重试（含错误原因）；
• [FAILED]: 4 (error)—— 重试耗尽后彻底失败，需人工检查对应 URL。

看到[FAILED]时，只需把失败的那几条 URL 修复后重新生成清单再跑一次，队列机制保证不会重复合入已成功的资产 ❌

总结

通过hygraph-examples的 using-asset-upload/ 示例，你掌握了三件批量导入资产到 Hygraph 的核心武器：

1. Asset Upload 端点：一个url参数即可完成远程资产入库；
2. Bee-Queue 队列：任务级重试 + 固定退避，让大批量导入"跑完为止"；
3. 状态日志：SUCCESS / RETRYING / FAILED三类输出，全程可追踪。

把它当作模板改一改，你的历史图库、迁移数据、第三方 CDN 资产，都能一键批量搬进 Hygraph 🎉

【免费下载链接】hygraph-examplesExample projects to help you get started with Hygraph项目地址: https://gitcode.com/gh_mirrors/hy/hygraph-examples