绑定(binding) 将您的 Worker 连接到 Developer Platform 上的外部资源,如 Images、R2 存储桶 或 KV 命名空间。
管理托管图像时,Images 绑定让您的 Worker 上传、列出、检索、更新和删除托管图像,而无需直接调用 REST API。hosted 命名空间暴露存储和管理操作。此绑定也可用于优化托管图像。
绑定可以在 Cloudflare 仪表板中为 Worker 配置,或在项目目录的 Wrangler 配置文件中配置。
要将 Images 绑定到 Worker,请在 Wrangler 配置文件中添加以下内容:
{
"images": {
"binding": "IMAGES", // available in your Worker on env.IMAGES
},
}[images]
binding = "IMAGES"在 Worker 代码中,您可以使用 env.IMAGES.hosted 命名空间管理托管图像。
env.IMAGES.hosted 命名空间让您上传和列出账户中的图像。要管理特定图像,调用 .image(imageId) 获取句柄,然后在其上调用方法。
将新图像上传到您的账户。您可以将图像字节作为流或 ArrayBuffer 传递。返回 ImageMetadata。
接受 ImageUploadOptions 对象中的以下选项:
idstring— 分配给图像的自定义 ID。如果省略,Cloudflare 生成 UUID。请参阅上传到自定义路径。filenamestring— 与图像关联的文件名。requireSignedURLsboolean— 设置查看图像是否需要签名 URL。默认为false。metadataRecord<string, unknown>— 与图像一起存储的任意元数据。creatorstring— 图像创建者的用户定义标识符。encoding'base64'— 如果提供的字节是 base64 编码的,设置为base64。绑定将在上传前解码它们。
创建 Direct Creator Upload URL,客户端可直接向该 URL 上传图像,而无需暴露 API token。返回 DirectUploadResult。
接受 DirectUploadOptions 对象中的以下选项:
idstringoptional — 分配给图像的自定义 ID。如果省略,Cloudflare 会自动生成 UUID。请参阅上传到自定义路径。metadataRecord<string, unknown>optional — 图像上传完成后一并存储的任意元数据。requireSignedURLsbooleanoptional — 设置上传后的图像查看是否需要签名 URL。默认为false。creatorstringoptional — 图像创建者的用户定义标识符。expiresInnumberoptional — 上传 URL 的有效时长(秒)。必须介于120和21600之间。默认为1800。
分页列出账户中的图像。返回 ImageList。
接受 ImageListOptions 对象中的以下选项:
limitnumber— 页面中返回的最大图像数。cursorstring— 上一次list()调用返回的延续令牌。第一页省略。sortOrder'asc' | 'desc'— 按uploaded时间戳排序结果的顺序。默认为asc。creatorstring— 将结果过滤为使用此创建者标识符上传的图像。filterImageListFilter— 按图像属性过滤结果。接受metadata字段以按自定义元数据过滤。
列出图像时,可以向 .list() 传入 filter.metadata,按自定义元数据字段返回图像。
filter.metadata 中的每个条目都是一个元数据字段名,其值设置该字段必须满足的条件。传入多个条目时,图像必须全部匹配才会被返回。
字段名只能包含字母、数字、下划线和点。如果元数据字段名包含其他字符(例如连字符或空格),则无法按该字段过滤。
要按嵌套字段过滤,请用点号分隔层级,例如 { "config.region": "eu-west" } 会匹配 { config: { region: "eu-west" } }。字段路径最多五层。
接受 ImageMetadataFilterOperators 对象中的以下运算符:
eqstring | number | boolean— 精确匹配字段。inArray<string> | Array<number>— 将字段与数组中的任意值匹配。数组最多接受 10 个值,字符串值不能包含管道字符(|)。gtnumber— 匹配大于该值的字段。gtenumber— 匹配大于或等于该值的字段。ltnumber— 匹配小于该值的字段。ltenumber— 匹配小于或等于该值的字段。
普通值是精确匹配的简写,因此 { status: "active" } 等价于 { status: { eq: "active" } }。
如果一个条目有多个条件,则图像必须满足每个条件才会被返回。要匹配范围,请在同一条目上组合两个运算符。例如,{ priority: { gte: 2, lte: 5 } } 会返回 priority 为 2 到 5 的图像。
单次调用最多接受五个条件。每个运算符计为一个条件,因此 { priority: { gte: 2, lte: 5 } } 这样的有界范围会占用两个条件。
引用不受支持的字段名、使用不受支持的运算符,或超过五个条件的请求会失败,而不是返回未过滤的结果。
export default {
async fetch(request, env) {
const { images } = await env.IMAGES.hosted.list({
filter: {
metadata: {
status: "active",
priority: { gte: 2, lte: 5 },
},
},
});
return Response.json(images.map((image) => image.id));
},
};export default {
async fetch(request, env) {
const { images } = await env.IMAGES.hosted.list({
filter: {
metadata: {
status: "active",
priority: { gte: 2, lte: 5 },
},
},
});
return Response.json(images.map((image) => image.id));
},
};返回单个托管图像的句柄。imageId 可以是 Cloudflare 生成的 UUID 或自定义 ID。
句柄本身不进行网络请求,因此构造成本很低。
获取图像的元数据。返回 ImageMetadata 或 null(如果不存在给定 ID 的图像)。
获取图像的原始字节。返回 ReadableStream<Uint8Array> 或 null(如果不存在给定 ID 的图像)。这流式传输原始上传的文件。将图像字节传递给 .input() 以在提供前优化,或使用 ImageMetadata.variants 或图像交付 URL 中返回的 URL 提供预定义变体。
更新图像的元数据或访问控制。所有字段都是可选的;仅更改指定的字段。返回带有更新值的 ImageMetadata。
接受 ImageUpdateOptions 对象中的以下选项:
requireSignedURLsboolean— 查看图像是否需要签名 URL。无法在使用自定义 ID 上传的图像上设置为true。metadataRecord<string, unknown>— 图像的替换元数据。这将替换现有元数据而不是合并。creatorstring— 图像创建者的用户定义标识符。
删除图像。如果图像已删除返回 true,如果不存在给定 ID 的图像返回 false。
为需要签名 URL 的图像生成签名图像交付 URL。返回 string。
返回签名 URL 可让浏览器直接获取私有图像,而无需通过您的 Worker 代理字节。URL 在 Cloudflare 侧签名,因此您的 Worker 永远不会处理账户签名密钥。
接受 ImageSignedUrlOptions 对象中的以下选项:
variantstring— 要提供的变体。expiresInnumberoptional — URL 的有效时长(秒)。如果省略,则 URL 不过期。keyNamestringoptional — 要使用的签名密钥名称。默认为default。
export default {
async fetch(request, env) {
if (!request.body) {
return new Response("Missing body", { status: 400 });
}
const image = await env.IMAGES.hosted.upload(request.body, {
filename: "upload.jpg",
metadata: { source: "worker" },
requireSignedURLs: false,
});
return Response.json(image);
},
};export default {
async fetch(request, env) {
if (!request.body) {
return new Response("Missing body", { status: 400 });
}
const image = await env.IMAGES.hosted.upload(request.body, {
filename: "upload.jpg",
metadata: { source: "worker" },
requireSignedURLs: false,
});
return Response.json(image);
},
};设置 encoding: "base64",绑定将在上传前为您解码 body。
export default {
async fetch(request, env) {
if (!request.body) {
return new Response("Missing body", { status: 400 });
}
const image = await env.IMAGES.hosted.upload(request.body, {
encoding: "base64",
filename: "upload.png",
});
return Response.json(image);
},
};export default {
async fetch(request, env) {
if (!request.body) {
return new Response("Missing body", { status: 400 });
}
const image = await env.IMAGES.hosted.upload(request.body, {
encoding: "base64",
filename: "upload.png",
});
return Response.json(image);
},
};export default {
async fetch(request, env) {
let cursor;
const ids = [];
do {
const page = await env.IMAGES.hosted.list({ limit: 100, cursor });
ids.push(...page.images.map((image) => image.id));
cursor = page.cursor;
} while (cursor);
return Response.json({ count: ids.length, ids });
},
};export default {
async fetch(request, env) {
let cursor: string | undefined;
const ids: string[] = [];
do {
const page = await env.IMAGES.hosted.list({ limit: 100, cursor });
ids.push(...page.images.map((image) => image.id));
cursor = page.cursor;
} while (cursor);
return Response.json({ count: ids.length, ids });
},
};export default {
async fetch(request, env) {
const details = await env.IMAGES.hosted.image("IMAGE_ID").details();
if (!details) {
return new Response("Not found", { status: 404 });
}
return Response.json(details);
},
};export default {
async fetch(request, env) {
const details = await env.IMAGES.hosted.image("IMAGE_ID").details();
if (!details) {
return new Response("Not found", { status: 404 });
}
return Response.json(details);
},
};export default {
async fetch(request, env) {
const bytes = await env.IMAGES.hosted.image("IMAGE_ID").bytes();
if (!bytes) {
return new Response("Not found", { status: 404 });
}
return new Response(bytes);
},
};export default {
async fetch(request, env) {
const bytes = await env.IMAGES.hosted.image("IMAGE_ID").bytes();
if (!bytes) {
return new Response("Not found", { status: 404 });
}
return new Response(bytes);
},
};export default {
async fetch(request, env) {
const updated = await env.IMAGES.hosted.image("IMAGE_ID").update({
metadata: { reviewed: true },
});
return Response.json(updated);
},
};export default {
async fetch(request, env) {
const updated = await env.IMAGES.hosted.image("IMAGE_ID").update({
metadata: { reviewed: true },
});
return Response.json(updated);
},
};export default {
async fetch(request, env) {
const deleted = await env.IMAGES.hosted.image("IMAGE_ID").delete();
return new Response(deleted ? "Deleted" : "Not found", {
status: deleted ? 200 : 404,
});
},
};export default {
async fetch(request, env) {
const deleted = await env.IMAGES.hosted.image("IMAGE_ID").delete();
return new Response(deleted ? "Deleted" : "Not found", {
status: deleted ? 200 : 404,
});
},
};将浏览器重定向到短期签名 URL,以便直接获取私有图像,而无需通过您的 Worker 流式传输字节。
export default {
async fetch(request, env) {
const url = await env.IMAGES.hosted.image("IMAGE_ID").signedUrl({
variant: "private",
expiresIn: 86_400,
});
return Response.redirect(url, 302);
},
};export default {
async fetch(request, env) {
const url = await env.IMAGES.hosted.image("IMAGE_ID").signedUrl({
variant: "private",
expiresIn: 86_400,
});
return Response.redirect(url, 302);
},
};创建一次性上传 URL 并将其返回给客户端,然后客户端可将图像直接上传到 Cloudflare,而无需您的 Worker 处理字节或 API token。
export default {
async fetch(request, env) {
const { id, uploadURL } = await env.IMAGES.hosted.createDirectUpload({
metadata: { userId: "abc123" },
requireSignedURLs: true,
expiresIn: 600,
});
return Response.json({ id, uploadURL });
},
};export default {
async fetch(request, env) {
const { id, uploadURL } = await env.IMAGES.hosted.createDirectUpload({
metadata: { userId: "abc123" },
requireSignedURLs: true,
expiresIn: 600,
});
return Response.json({ id, uploadURL });
},
};此示例从远程 URL 获取图像,将其上传到 Images 账户,并返回第一个变体 URL。
export default {
async fetch(request, env) {
const upstream = await fetch("https://example.com/photo.jpg");
if (!upstream.ok || !upstream.body) {
return new Response("Upstream fetch failed", { status: 502 });
}
const image = await env.IMAGES.hosted.upload(upstream.body, {
filename: "photo.jpg",
metadata: { source: "example.com" },
});
return Response.json({
id: image.id,
variant: image.variants[0],
});
},
};export default {
async fetch(request, env) {
const upstream = await fetch("https://example.com/photo.jpg");
if (!upstream.ok || !upstream.body) {
return new Response("Upstream fetch failed", { status: 502 });
}
const image = await env.IMAGES.hosted.upload(upstream.body, {
filename: "photo.jpg",
metadata: { source: "example.com" },
});
return Response.json({
id: image.id,
variant: image.variants[0],
});
},
};检索、创建或更新图像的操作返回。
idstring- 图像的唯一标识符。
filenamestringoptional- 上传时提供的原始文件名。
uploadedstringoptional- 图像上传的日期和时间,ISO 8601 字符串。
requireSignedURLsboolean- 访问此图像是否需要签名 URL。请参阅提供私有图像。
metaRecord<string, unknown>optional- 与图像关联的用户提供的元数据。
variantsArray<string>- 账户上配置的每个变体的完整 URL。请参阅创建变体。
draftbooleanoptional- 图像是否处于草稿状态(尚未上传字节)。草稿通常仅在账户使用 Direct Creator Uploads 时可见。
creatorstringoptional- 图像创建者的用户定义标识符。
由 list() 返回。
imagesArray<ImageMetadata>- 此页结果中的图像。
cursorstringoptional- 传递给下一次
list()调用的延续令牌。仅在有更多结果时存在。
- 传递给下一次
listCompleteboolean- 没有更多页面时为
true,否则为false。
- 没有更多页面时为
由 createDirectUpload() 返回。
idstring- 上传后的图像将使用的 ID。
uploadURLstring- 客户端将图像字节上传到的一次性 URL。
失败的方法抛出 ImagesError — .upload()、.list()、.createDirectUpload()、.update() 和 .signedUrl() — 具有以下属性:
codenumber- 标识失败模式的数字错误代码。
messagestring- 错误的人类可读描述。
获取单张图像的方法 — .details()、.bytes() 和 .delete() — 对于"未找到"返回 null 或 false 而不是抛出。
您可能希望将可能抛出的操作包装在 try...catch 块中。
运行 wrangler dev 时,管理托管图像的操作由本地 mock 提供,将图像存储在嵌入式 KV 命名空间中。mock 支持本页记录的每个方法,因此您可以离线开发和测试 Worker。
mock 仅适用于本地开发。要从本地环境使用真实的 Images 服务,请运行 wrangler dev --remote。
- 使用 Workers 优化 — 使用绑定从 Worker 优化图像。
- 通过 REST API 上传 — 等效的 HTTP API。
- 管理托管图像 — 用于管理存储图像的仪表板和 API 工作流。