存储图片变换

使用存储服务进行图片变换

Supabase Storage 提供了实时优化和调整图像大小的功能。存储在任何存储桶中的图像都可以进行转换和优化，以实现快速交付。

图像调整功能目前仅适用于专业版及以上计划。

获取转换后图像的公开URL

我们的客户端库方法如 getPublicUrl 和 createSignedUrl 支持 transform 选项。这将返回提供转换后图像的URL。

1
2
3
4
5
6
7
8
9
10
import { createClient } from '@supabase/supabase-js'const supabase = createClient('your_project_url', 'your_supabase_api_key')// ---cut---supabase.storage.from('bucket').getPublicUrl('image.jpg', {  transform: {    width: 500,    height: 600,  },})

示例URL可能如下所示：

1
https://project_id.supabase.co/storage/v1/render/image/public/bucket/image.jpg?width=500&height=600`

使用转换选项生成签名URL

要在固定时间内分享私有存储桶中经过转换的图片，可以在创建签名URL时提供转换选项：

1
2
3
4
5
6
7
8
9
10
import { createClient } from '@supabase/supabase-js'const supabase = createClient('your_project_url', 'your_supabase_api_key')// ---cut---supabase.storage.from('bucket').createSignedUrl('image.jpg', 60000, {  transform: {    width: 200,    height: 200,  },})

转换选项会被嵌入到URL附带的令牌中——一旦签名后这些选项就无法更改。

下载图片

要下载经过转换的图片，请将 transform 选项传递给 download 函数。

1
2
3
4
5
6
7
8
9
10
import { createClient } from '@supabase/supabase-js'const supabase = createClient('your_project_url', 'your_supabase_api_key')// ---cut---supabase.storage.from('bucket').download('image.jpg', {  transform: {    width: 800,    height: 300,  },})

自动图片优化 (WebP)

使用图片转换API时，Storage会自动检测客户端支持的最佳格式并返回相应格式的图片，无需任何代码更改。例如，当您使用Chrome浏览器查看JPEG图片并应用转换选项时，您会发现图片被自动优化为webp格式。

这一优化将显著减少传输给用户的带宽消耗，使您的应用程序加载速度大幅提升。

目前我们仅支持WebP格式。AVIF格式支持将在近期推出。

禁用自动优化功能：

如果您希望返回图像的原始格式并退出自动图像优化检测，可以在请求转换后的图像时传递 format=origin 参数。该功能从 JavaScript SDK v2.2.0 版本开始支持。

1
2
3
4
5
6
7
8
9
10
11
import { createClient } from '@supabase/supabase-js'const supabase = createClient('your_project_url', 'your_supabase_api_key')// ---cut---await supabase.storage.from('bucket').download('image.jpeg', {  transform: {    width: 200,    height: 200,    format: 'origin',  },})

Next.js 加载器

您可以使用 Supabase 图片转换功能通过自定义加载器来优化 Next.js 中的图片。

首先，在您的 Next.js 项目中创建一个 supabase-image-loader.js 文件，并导出一个默认函数：

1
2
3
4
5
const projectId = '' // 您的 Supabase 项目 IDexport default function supabaseLoader({ src, width, quality }) {  return `https://${projectId}.supabase.co/storage/v1/render/image/public/${src}?width=${width}&quality=${quality || 75}`}

然后在 nextjs.config.js 文件中添加以下配置，指示 Next.js 使用我们的自定义加载器：

1
2
3
4
5
6
module.exports = {  images: {    loader: 'custom',    loaderFile: './supabase-image-loader.js',  },}

完成以上步骤后，您就可以使用 Next.js 提供的 Image 组件了：

1
2
3
4
5
import Image from 'next/image'const MyImage = (props) => {  return <Image src="bucket/image.png" alt="作者照片" width={500} height={500} />}

转换选项

目前我们支持以下几种转换选项，主要用于图片优化、调整大小和裁剪：

优化图像质量

您可以通过向 quality 参数传递 20 到 100 之间的值（100 表示最高质量）来设置返回图像的质量。该参数默认值为 80。

示例：

1
2
3
4
5
6
7
8
9
import { createClient } from '@supabase/supabase-js'const supabase = createClient('your_project_url', 'your_supabase_api_key')// ---cut---supabase.storage.from('bucket').download('image.jpg', {  transform: {    quality: 50,  },})

调整图像尺寸

您可以使用 width 和 height 参数将图像调整为特定尺寸。如果只指定一个参数，图像将按比例调整大小并进行裁剪以保持宽高比。

调整模式

您可以根据需求使用不同的调整模式，每种模式采用不同的方法来调整图像大小：

使用 resize 参数并选择以下值之一：

cover：保持宽高比调整图像大小以填充给定尺寸，并裁剪超出部分（默认模式）
contain：保持宽高比调整图像大小以适应给定尺寸
fill：不保持宽高比直接调整图像大小

示例：

1
2
3
4
5
6
7
8
9
10
11
import { createClient } from '@supabase/supabase-js'const supabase = createClient('your_project_url', 'your_supabase_api_key')// ---cut---supabase.storage.from('bucket').download('image.jpg', {  transform: {    width: 800,    height: 300,    resize: 'contain', // 'cover' | 'fill'  },})

限制条件

宽度和高度必须是1-2500之间的整数值
图片大小不能超过25MB
图片分辨率不能超过50MP（5000万像素）

支持的图片格式

格式	扩展名	支持来源	支持输出
PNG	`png`	☑️	☑️
JPEG	`jpg`	☑️	☑️
WebP	`webp`	☑️	☑️
AVIF	`avif`	☑️	☑️
GIF	`gif`	☑️	☑️
ICO	`ico`	☑️	☑️
SVG	`svg`	☑️	☑️
HEIC	`heic`	☑️	❌
BMP	`bmp`	☑️	☑️
TIFF	`tiff`	☑️	☑️

定价方案

每1000张原始图片收费$5 。仅在使用量超出订阅计划配额时才会收费。

计数在每个计费周期开始时重置。

计划	配额	超额使用收费
专业版	100	每1000张原始图片收费$5
团队版	100	每1000张原始图片收费$5
企业版	自定义	自定义

如需了解费用计算的详细说明，请参阅管理存储图片转换用量。

自托管方案

与其他Supabase产品一样，我们的图片缩放和优化解决方案也支持自托管。底层我们使用了imgproxy技术。

imgproxy配置：

使用以下配置部署imgproxy容器：

1
2
3
4
5
imgproxy:  image: darthsim/imgproxy  environment:    - IMGPROXY_ENABLE_WEBP_DETECTION=true    - IMGPROXY_JPEG_PROGRESSIVE=true

注意：请确保该服务仅能在内部网络中访问，不要暴露给公共互联网

存储API配置：

部署完imgproxy后，我们需要在自托管的storage-api服务中配置以下环境变量：

1
2
ENABLE_IMAGE_TRANSFORMATION=trueIMGPROXY_URL=yourinternalimgproxyurl.internal.com