存储图片转换

Supabase Storage 提供了即时优化和调整图片大小的功能。你存储在桶里的任何图片都可以被转换和优化，以实现快速传输。

🌐 Supabase Storage offers the functionality to optimize and resize images on the fly. Any image stored in your buckets can be transformed and optimized for fast delivery.

管理图片转换 #

🌐 Manage image transformations

你可以在仪表板的 存储 > 设置 部分为你的项目启用或禁用图片转换，并切换 启用图片转换 选项。

🌐 You can enable or disable Image Transformations for your project from the Storage > Settings section of the Dashboard and toggle the Enable Image Transformations option.

获取转换后图片的公共网址 #

🌐 Get a public URL for a transformed image

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

🌐 Our client libraries methods like getPublicUrl and createSignedUrl support the transform option. This returns the URL that serves the transformed image.

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

一个示例网址可能看起来像这样：

🌐 An example URL could look like this:

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

为 URL 添加带有转换选项的签名 #

🌐 Signing URLs with transformation options

要在私有存储桶中分享一个转换后的图片，并设定固定的有效时间，请在创建签名 URL 时提供 transform 选项：

🌐 To share a transformed image in a private bucket for a fixed amount of time, provide the transform option when you create the signed URL:

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

转换选项已经嵌入到附加在 URL 上的令牌里——一旦签名就无法更改。

🌐 The transformation options are embedded into the token attached to the URL — they cannot be changed once signed.

正在下载图片 #

🌐 Downloading images

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

🌐 To download a transformed image, pass the transform option to the download function.

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

自动图片优化（WebP） #

🌐 Automatic image optimization (WebP)

在使用图片转换 API 时，Storage 会自动找到客户端支持的最佳格式并返回给客户端，无需任何代码更改。例如，如果你在使用 Chrome 查看 JPEG 图片并使用转换选项，你会发现图片会自动被优化为 webp 格式。

🌐 When using the image transformation API, Storage will automatically find the best format supported by the client and return that to the client, without any code change. For instance, if you use Chrome when viewing a JPEG image and using transformation options, you'll see that images are automatically optimized as webp images.

因此，这会减少你发送给用户的数据量，你的应用加载速度也会快很多。

🌐 As a result, this will lower the egress that you send to your users and your application will load much faster.

禁用自动优化：

如果你想要返回图片的原始格式，并选择不使用自动图片优化检测，你可以在请求转换后的图片时传递 format=origin 参数，这在从 v2.2.0 开始的 JavaScript SDK 中也支持。

🌐 In case you'd like to return the original format of the image and opt-out from the automatic image optimization detection, you can pass the format=origin parameter when requesting a transformed image, this is also supported in the JavaScript SDK starting from v2.2.0

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

Next.js 加载器 #

🌐 Next.js loader

你可以使用 Supabase 图片转化来通过自定义 Loader 优化你的 Next.js 图片。

🌐 You can use Supabase Image Transformation to optimize your Next.js images using a custom Loader.

要开始，在你的 Next.js 项目中创建一个 supabase-image-loader.js 文件，并导出一个默认函数：

🌐 To get started, create a supabase-image-loader.js file in your Next.js project which exports a default function:

1
const projectId = '' // your supabase project id
2
3
export default function supabaseLoader({ src, width, quality }) {
4
  return `https://${projectId}.supabase.co/storage/v1/render/image/public/${src}?width=${width}&quality=${quality || 75}`
5
}

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

🌐 In your next.config.js file add the following configuration to instruct Next.js to use our custom loader

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

此时你已经可以使用 Next.js 提供的 Image 组件了

🌐 At this point you are ready to use the Image component provided by Next.js

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

转换选项 #

🌐 Transformation options

我们目前支持一些转换选项，主要用于优化、调整大小和裁剪图片。

🌐 We currently support a few transformation options focusing on optimizing, resizing, and cropping images.

优化中 #

🌐 Optimizing

你可以通过向 quality 参数传入 20 到 100 之间的数值来设置返回图片的质量（100 为最高质量）。该参数默认值是 80。

🌐 You can set the quality of the returned image by passing a value from 20 to 100 (with 100 being the highest quality) to the quality parameter. This parameter defaults to 80.

示例：

🌐 Example:

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

调整大小 #

🌐 Resizing

你可以使用 width 和 height 参数将图片调整到特定尺寸。如果只指定一个参数，图片将会按比例调整并裁剪。

🌐 You can use width and height parameters to resize an image to a specific dimension. If only one parameter is specified, the image will be resized and cropped, maintaining the aspect ratio.

模式 #

🌐 Modes

你可以使用不同的调整大小模式来满足你的需求，每种模式都采用不同的方法来调整图片大小：

🌐 You can use different resizing modes to fit your needs, each of them uses a different approach to resize the image:

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

🌐 Use the resize parameter with one of the following values:

• cover：调整图片大小，同时保持长宽比以填充给定尺寸，并裁切突出部分。（默认）
• contain：在保持纵横比的情况下调整图片大小，以适应指定尺寸。
• fill ：调整图片大小，不保持宽高比。

示例：

🌐 Example:

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

限制 #

🌐 Limits

• 宽度和高度必须是 1 到 2500 之间的整数。
• 图片大小不能超过25MB。
• 图片分辨率不能超过50百万像素。

支持的图片格式 #

🌐 Supported image formats

$5 每 1,000 张原始图片。只有超过订阅计划配额的使用才会收费。

要详细了解费用是如何计算的，请参考管理存储图片转换使用情况。

🌐 For a detailed breakdown of how charges are calculated, refer to Manage Storage Image Transformations usage.

自托管 #

🌐 Self hosting

我们的图片调整大小和优化解决方案可以像其他 Supabase 产品一样自托管。在底层，我们使用 imgproxy。

🌐 Our solution to image resizing and optimization can be self-hosted as with any other Supabase product. Under the hood we use imgproxy.

imgproxy 配置： #

🌐 imgproxy configuration:

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

🌐 Deploy an imgproxy container with the following configuration:

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

注意：确保这个服务只能在内部网络中访问，不能向公共互联网开放

🌐 Note: make sure that this service can only be reachable within an internal network and not exposed to the public internet

存储 API 配置： #

🌐 Storage API configuration:

一旦部署了 imgproxy，我们需要在你自托管的 storage-api 服务中配置几个环境变量，如下所示：

🌐 Once imgproxy is deployed we need to configure a couple of environment variables in your self-hosted storage-api service as follows:

1
ENABLE_IMAGE_TRANSFORMATION=true
2
IMGPROXY_URL=yourinternalimgproxyurl.internal.com