JavaScript客户端库

@supabase/supabase-js

本参考文档记录了 Supabase 的同构 JavaScript 库 supabase-js 中可用的每个对象和方法。您可以使用 supabase-js 与您的 Postgres 数据库交互、监听数据库更改、调用 Deno 边缘函数、构建登录和用户管理功能以及管理大型文件。

要将 SQL 查询转换为 supabase-js 调用，请使用 SQL 到 REST API 转换器。

安装

作为包安装#

您可以通过终端安装 @supabase/supabase-js。

1
npm install @supabase/supabase-js

通过 CDN 安装#

您可以通过 CDN 链接安装 @supabase/supabase-js。

1
<script src="https://cdn.jsdelivr.net.cn/npm/@supabase/supabase-js@2"></script>
2
//or
3
<script src="https://unpkg.com/@supabase/supabase-js@2"></script>

在 Deno 运行时中使用#

您可以通过 JSR 在 Deno 运行时中使用 supabase-js

1
import { createClient } from 'npm:@supabase/supabase-js@2'

初始化

为在浏览器中使用创建一个新的客户端。

参数

supabaseUrlstring
您在项目仪表板中创建新项目时提供的唯一 Supabase URL。
supabaseKeystring
您在项目仪表板中创建新项目时提供的唯一 Supabase Key。
options
可选
SupabaseClientOptions

1
import { createClient } from '@supabase/supabase-js'
2
3
// Create a single supabase client for interacting with your database
4
const supabase = createClient('https://xyzcompany.supabase.co', 'publishable-or-anon-key')

TypeScript 支持

supabase-js 具有 TypeScript 支持，用于类型推断、自动完成、类型安全查询等。

使用 TypeScript，supabase-js 会检测诸如 not null 约束和生成列之类的内容。可为空的列在您选择该列时会被键入为 T | null。在插入生成列时，会显示类型错误。

supabase-js 还会检测表之间的关系。具有一对多关系的相关表被键入为 T[]。同样，具有多对一关系的相关表被键入为 T | null。

生成 TypeScript 类型#

您可以使用 Supabase CLI 生成类型。您还可以从仪表板生成类型。

1
supabase gen types typescript --project-id abcdefghijklmnopqrst > database.types.ts

这些类型是从您的数据库模式生成的。给定一个表 public.movies，生成的类型将如下所示

1
create table public.movies (
2
  id bigint generated always as identity primary key,
3
  name text not null,
4
  data jsonb null
5
);

1
export type Json = string | number | boolean | null | { [key: string]: Json | undefined } | Json[]
2
3
export interface Database {
4
  public: {
5
    Tables: {
6
      movies: {
7
        Row: {               // the data expected from .select()
8
          id: number
9
          name: string
10
          data: Json | null
11
        }
12
        Insert: {            // the data to be passed to .insert()
13
          id?: never         // generated columns must not be supplied
14
          name: string       // `not null` columns with no default must be supplied
15
          data?: Json | null // nullable columns can be omitted
16
        }
17
        Update: {            // the data to be passed to .update()
18
          id?: never
19
          name?: string      // `not null` columns are optional on .update()
20
          data?: Json | null
21
        }
22
      }
23
    }
24
  }
25
}

使用 TypeScript 类型定义#

您可以像这样将类型定义提供给 supabase-js

1
import { createClient } from '@supabase/supabase-js'
2
import { Database } from './database.types'
3
4
const supabase = createClient<Database>(
5
  process.env.SUPABASE_URL,
6
  process.env.SUPABASE_ANON_KEY
7
)

用于表和连接的辅助类型#

您可以使用以下辅助类型使生成的 TypeScript 类型更易于使用。

有时生成的类型并不如您所期望。例如，视图的列可能显示为可为空，而您期望它为 not null。使用 type-fest，您可以像这样覆盖类型

1
export type Json = // ...
2
3
export interface Database {
4
  // ...
5
}

1
import { MergeDeep } from 'type-fest'
2
import { Database as DatabaseGenerated } from './database-generated.types'
3
export { Json } from './database-generated.types'
4
5
// Override the type for a specific column in a view:
6
export type Database = MergeDeep<
7
  DatabaseGenerated,
8
  {
9
    public: {
10
      Views: {
11
        movies_view: {
12
          Row: {
13
            // id is a primary key in public.movies, so it must be `not null`
14
            id: number
15
          }
16
        }
17
      }
18
    }
19
  }
20
>

您还可以根据需要覆盖单个成功响应的类型

1
// Partial type override allows you to only override some of the properties in your results
2
const { data } = await supabase.from('countries').select().overrideTypes<Array<{ id: string }>>()
3
// For a full replacement of the original return type use the `{ merge: false }` property as second argument
4
const { data } = await supabase
5
  .from('countries')
6
  .select()
7
  .overrideTypes<Array<{ id: string }>, { merge: false }>()
8
// Use it with `maybeSingle` or `single`
9
const { data } = await supabase.from('countries').select().single().overrideTypes<{ id: string }>()

生成的类型为访问表和枚举提供了简写。

1
import { Database, Tables, Enums } from "./database.types.ts";
2
3
// Before 😕
4
let movie: Database['public']['Tables']['movies']['Row'] = // ...
5
6
// After 😍
7
let movie: Tables<'movies'>

复杂查询的响应类型#

supabase-js 始终返回一个 data 对象（成功）和一个 error 对象（不成功的请求）。

这些辅助类型提供了来自任何查询的结果类型，包括数据库连接的嵌套类型。

给定一个具有城市和国家/地区之间关系的模式，我们可以获得嵌套的 CountriesWithCities 类型

1
create table countries (
2
  "id" serial primary key,
3
  "name" text
4
);
5
6
create table cities (
7
  "id" serial primary key,
8
  "name" text,
9
  "country_id" int references "countries"
10
);

1
import { QueryResult, QueryData, QueryError } from '@supabase/supabase-js'
2
3
const countriesWithCitiesQuery = supabase
4
  .from("countries")
5
  .select(`
6
    id,
7
    name,
8
    cities (
9
      id,
10
      name
11
    )
12
  `);
13
type CountriesWithCities = QueryData<typeof countriesWithCitiesQuery>;
14
15
const { data, error } = await countriesWithCitiesQuery;
16
if (error) throw error;
17
const countriesWithCities: CountriesWithCities = data;

获取数据

select(columns?, options?)

对表或视图执行 SELECT 查询。

默认情况下，Supabase 项目返回最多 1,000 行。可以在您的项目的 API 设置中更改此设置。建议将其保持较低，以限制意外或恶意请求的有效负载大小。您可以使用 range() 查询来分页您的数据。
select() 可以与过滤器结合使用
select() 可以与修饰符结合使用
apikey 如果您使用 Supabase 平台和应该避免作为列名，则是一个保留关键字。

参数

列
可选
查询
要检索的列，用逗号分隔。列可以在返回时使用 customName:columnName 重命名
options
可选
object
命名参数

1
const { data, error } = await supabase
2
  .from('characters')
3
  .select()

插入数据

insert(values, options?)

参数

values以下选项之一
- 选项 1Row
- 选项 2Array<Row>
options
可选
object

1
const { error } = await supabase
2
  .from('countries')
3
  .insert({ id: 1, name: 'Mordor' })

更新数据

update(values, options)

执行 UPDATE 到表或视图。

默认情况下，更新的行不会返回。要返回它，请在过滤器之后使用 .select() 链式调用。

update() 始终应与过滤器结合使用，以针对您希望更新的项目。

参数

valuesRow
要更新的值
optionsobject
命名参数

1
const { error } = await supabase
2
  .from('instruments')
3
  .update({ name: 'piano' })
4
  .eq('id', 1)

更新或插入数据

upsert(values, options?)

要使用 upsert，必须在 values 中包含主键。

参数

values以下选项之一
- 选项 1Row
- 选项 2Array<Row>
options
可选
object

1
const { data, error } = await supabase
2
  .from('instruments')
3
  .upsert({ id: 1, name: 'piano' })
4
  .select()

删除数据

delete(options)

执行 DELETE 到表或视图。

默认情况下，删除的行不会返回。要返回它，请在过滤器之后使用 .select() 链式调用。

delete() 始终应与过滤器结合使用，以针对您希望删除的项目。
如果您使用带有过滤器的 delete() 并且启用了 RLS，则只会删除通过 SELECT 策略可见的行。请注意，默认情况下没有行可见，因此您至少需要一个使行可见的 SELECT/ALL 策略。
当使用 delete().in() 时，请指定一个值数组以使用单个查询为多个行定位。这对于批量删除具有共同标准的条目（例如按 ID 删除用户）特别有用。请确保您提供的数组准确表示您打算删除的所有记录，以避免意外删除数据。

参数

optionsobject
命名参数

1
const response = await supabase
2
  .from('countries')
3
  .delete()
4
  .eq('id', 1)

调用 Postgres 函数

rpc(fn, args, options)

执行函数调用。

参数

fnFnName
要调用的函数名称
argsArgs
要传递给函数调用的参数
optionsobject
命名参数

1
const { data, error } = await supabase.rpc('hello_world')

使用过滤器

过滤器允许你仅返回匹配特定条件的行。

过滤器可用于 select()、update()、upsert() 和 delete() 查询。

如果 Postgres 函数返回表响应，您也可以应用过滤器。

1
const { data, error } = await supabase
2
  .from('instruments')
3
  .select('name, section_id')
4
  .eq('name', 'violin')    // Correct
5
6
const { data, error } = await supabase
7
  .from('instruments')
8
  .eq('name', 'violin')    // Incorrect
9
  .select('name, section_id')

列等于一个值

eq(column, value)

仅匹配 column 等于 value 的行。

要检查 column 的值是否为 NULL，您应该使用 .is() 代替。

参数

columnColumnName
要过滤的列
value
要过滤的值

返回类型

this

1
const { data, error } = await supabase
2
  .from('characters')
3
  .select()
4
  .eq('name', 'Leia')

列不等于一个值

neq(column, value)

仅匹配 column 不等于 value 的行。

参数

columnColumnName
要过滤的列
value
要过滤的值

返回类型

this

1
const { data, error } = await supabase
2
  .from('characters')
3
  .select()
4
  .neq('name', 'Leia')

列大于一个值

gt(column, value)

参数

column以下选项之一
- 选项 1ColumnName
- 选项 2string
value以下选项之一
- 选项 1Row['ColumnName']
- 选项 2unknown

返回类型

this

1
const { data, error } = await supabase
2
  .from('characters')
3
  .select()
4
  .gt('id', 2)

列大于或等于一个值

gte(column, value)

参数

column以下选项之一
- 选项 1ColumnName
- 选项 2string
value以下选项之一
- 选项 1Row['ColumnName']
- 选项 2unknown

返回类型

this

1
const { data, error } = await supabase
2
  .from('characters')
3
  .select()
4
  .gte('id', 2)

列小于一个值

lt(column, value)

参数

column以下选项之一
- 选项 1ColumnName
- 选项 2string
value以下选项之一
- 选项 1Row['ColumnName']
- 选项 2unknown

返回类型

this

1
const { data, error } = await supabase
2
  .from('characters')
3
  .select()
4
  .lt('id', 2)

列小于或等于一个值

lte(column, value)

参数

column以下选项之一
- 选项 1ColumnName
- 选项 2string
value以下选项之一
- 选项 1Row['ColumnName']
- 选项 2unknown

返回类型

this

1
const { data, error } = await supabase
2
  .from('characters')
3
  .select()
4
  .lte('id', 2)

列匹配一个模式

like(column, pattern)

参数

column以下选项之一
- 选项 1ColumnName
- 选项 2string
patternstring

返回类型

this

1
const { data, error } = await supabase
2
  .from('characters')
3
  .select()
4
  .like('name', '%Lu%')

列匹配一个不区分大小写的模式

ilike(column, pattern)

参数

column以下选项之一
- 选项 1ColumnName
- 选项 2string
patternstring

返回类型

this

1
const { data, error } = await supabase
2
  .from('characters')
3
  .select()
4
  .ilike('name', '%lu%')

列是一个值

is(column, value)

参数

column以下选项之一
- 选项 1ColumnName
- 选项 2string
value以下选项之一
- 选项 1null
- 选项 2boolean

返回类型

this

1
const { data, error } = await supabase
2
  .from('countries')
3
  .select()
4
  .is('name', null)

列在一个数组中

in(column, values)

仅匹配 column 包含在 values 数组中的行。

参数

columnColumnName
要过滤的列
valuesArray
要过滤的数组值

返回类型

this

1
const { data, error } = await supabase
2
  .from('characters')
3
  .select()
4
  .in('name', ['Leia', 'Han'])

列包含数组中的每个元素

contains(column, value)

参数

column以下选项之一
- 选项 1ColumnName
- 选项 2string
value以下选项之一
- 选项 1string
- 选项 2Record<string, unknown>
- 选项 3Array<Row['ColumnName']>
- 选项 4Array<unknown>

返回类型

this

1
const { data, error } = await supabase
2
  .from('issues')
3
  .select()
4
  .contains('tags', ['is:open', 'priority:low'])

包含在值中

containedBy(column, value)

参数

column以下选项之一
- 选项 1ColumnName
- 选项 2string
value以下选项之一
- 选项 1string
- 选项 2Record<string, unknown>
- 选项 3Array<Row['ColumnName']>
- 选项 4Array<unknown>

返回类型

this

1
const { data, error } = await supabase
2
  .from('classes')
3
  .select('name')
4
  .containedBy('days', ['monday', 'tuesday', 'wednesday', 'friday'])

大于一个范围

rangeGt(column, range)

参数

column以下选项之一
- 选项 1ColumnName
- 选项 2string
rangestring

返回类型

this

1
const { data, error } = await supabase
2
  .from('reservations')
3
  .select()
4
  .rangeGt('during', '[2000-01-02 08:00, 2000-01-02 09:00)')

大于或等于一个范围

rangeGte(column, range)

参数

column以下选项之一
- 选项 1ColumnName
- 选项 2string
rangestring

返回类型

this

1
const { data, error } = await supabase
2
  .from('reservations')
3
  .select()
4
  .rangeGte('during', '[2000-01-02 08:30, 2000-01-02 09:30)')

小于一个范围

rangeLt(column, range)

参数

column以下选项之一
- 选项 1ColumnName
- 选项 2string
rangestring

返回类型

this

1
const { data, error } = await supabase
2
  .from('reservations')
3
  .select()
4
  .rangeLt('during', '[2000-01-01 15:00, 2000-01-01 16:00)')

小于或等于一个范围

rangeLte(column, range)

参数

column以下选项之一
- 选项 1ColumnName
- 选项 2string
rangestring

返回类型

this

1
const { data, error } = await supabase
2
  .from('reservations')
3
  .select()
4
  .rangeLte('during', '[2000-01-01 14:00, 2000-01-01 16:00)')

与范围互斥

rangeAdjacent(column, range)

参数

column以下选项之一
- 选项 1ColumnName
- 选项 2string
rangestring

返回类型

this

1
const { data, error } = await supabase
2
  .from('reservations')
3
  .select()
4
  .rangeAdjacent('during', '[2000-01-01 12:00, 2000-01-01 13:00)')

具有共同元素

overlaps(column, value)

参数

column以下选项之一
- 选项 1ColumnName
- 选项 2string
value以下选项之一
- 选项 1string
- 选项 2Array<Row['ColumnName']>
- 选项 3Array<unknown>

返回类型

this

1
const { data, error } = await supabase
2
  .from('issues')
3
  .select('title')
4
  .overlaps('tags', ['is:closed', 'severity:high'])

匹配一个字符串

textSearch(column, query, options?)

有关更多信息，请参阅 Postgres 全文搜索。

参数

column以下选项之一
- 选项 1ColumnName
- 选项 2string
querystring
options
可选
object

返回类型

this

1
const result = await supabase
2
  .from("texts")
3
  .select("content")
4
  .textSearch("content", `'eggs' & 'ham'`, {
5
    config: "english",
6
  });

匹配关联值

match(query)

参数

query以下选项之一
- 选项 1Record<ColumnName, Row['ColumnName']>
- 选项 2Record<string, unknown>

返回类型

this

1
const { data, error } = await supabase
2
  .from('characters')
3
  .select('name')
4
  .match({ id: 2, name: 'Leia' })

不匹配过滤器

not(column, operator, value)

not() 要求您使用原始 PostgREST 语法来过滤值。

1
.not('id', 'in', '(5,6,7)')  // Use `()` for `in` filter
2
.not('arraycol', 'cs', '{"a","b"}')  // Use `cs` for `contains()`, `{}` for array values

参数

column以下选项之一
- 选项 1ColumnName
- 选项 2string
operator以下选项之一
- 选项 1FilterOperator
- 选项 2string
value以下选项之一
- 选项 1Row['ColumnName']
- 选项 2unknown

返回类型

this

1
const { data, error } = await supabase
2
  .from('countries')
3
  .select()
4
  .not('name', 'is', null)

匹配至少一个过滤器

or(filters, options)

仅匹配满足至少一个过滤器的行。

与大多数过滤器不同，filters 按原样使用，需要遵循 PostgREST 语法。您还需要确保它经过适当的清理。

目前无法对多个表执行 .or() 过滤器。

or() 期望你使用原始的 PostgREST 语法来表示筛选器的名称和值。

1
.or('id.in.(5,6,7), arraycol.cs.{"a","b"}')  // Use `()` for `in` filter, `{}` for array values and `cs` for `contains()`.
2
.or('id.in.(5,6,7), arraycol.cd.{"a","b"}')  // Use `cd` for `containedBy()`

参数

filtersstring
要使用的过滤器，遵循 PostgREST 语法
optionsobject
命名参数

返回类型

this

1
const { data, error } = await supabase
2
  .from('characters')
3
  .select('name')
4
  .or('id.eq.2,name.eq.Han')

匹配过滤器

filter(column, operator, value)

filter() 期望您使用原始 PostgREST 语法来获取过滤器的值。

1
.filter('id', 'in', '(5,6,7)')  // Use `()` for `in` filter
2
.filter('arraycol', 'cs', '{"a","b"}')  // Use `cs` for `contains()`, `{}` for array values

参数

column以下选项之一
- 选项 1ColumnName
- 选项 2string
operator以下选项之一
- 选项 1FilterOperator
- Option 2"not.match"
- Option 3"not.eq"
- Option 4"not.neq"
- Option 5"not.gt"
- Option 6"not.gte"
- Option 7"not.lt"
- Option 8"not.lte"
- Option 9"not.like"
- Option 10"not.ilike"
- Option 11"not.is"
- Option 12"not.isdistinct"
- Option 13"not.in"
- Option 14"not.cs"
- Option 15"not.cd"
- Option 16"not.sl"
- Option 17"not.sr"
- Option 18"not.nxl"
- Option 19"not.nxr"
- Option 20"not.adj"
- Option 21"not.ov"
- Option 22"not.fts"
- Option 23"not.plfts"
- Option 24"not.phfts"
- Option 25"not.wfts"
- Option 26"not.imatch"
- Option 27string
valueunknown

返回类型

this

1
const { data, error } = await supabase
2
  .from('characters')
3
  .select()
4
  .filter('name', 'in', '("Han","Yoda")')

使用修饰符

过滤器在行级别上工作——它们允许您仅返回匹配特定条件的行，而不会更改行的形状。修饰符是所有不符合该定义的内容——允许您更改响应的格式（例如，返回 CSV 字符串）。

修饰符必须在过滤器之后指定。某些修饰符仅适用于返回行的查询（例如，select() 或返回表响应的函数的 rpc()）。

插入后返回数据

select(columns?)

对查询结果执行 SELECT。

默认情况下，.insert()、.update()、.upsert() 和 .delete() 不会返回修改后的行。通过调用此方法，修改后的行将在 data 中返回。

参数

列
可选
查询
要检索的列，用逗号分隔

1
const { data, error } = await supabase
2
  .from('characters')
3
  .upsert({ id: 1, name: 'Han Solo' })
4
  .select()

对结果进行排序

order(column, options?)

参数

column以下选项之一
- 选项 1ColumnName
- 选项 2string
options
可选
object

返回类型

this

1
const { data, error } = await supabase
2
  .from('characters')
3
  .select('id, name')
4
  .order('id', { ascending: false })

限制返回的行数

limit(count, options)

通过 count 限制查询结果。

参数

countnumber
要返回的最大行数
optionsobject
命名参数

返回类型

this

1
const { data, error } = await supabase
2
  .from('characters')
3
  .select('name')
4
  .limit(1)

将查询限制在一个范围内

range(from, to, options)

通过从偏移量 from 开始到偏移量 to 结束来限制查询结果。仅返回此范围内的记录。这尊重查询顺序，如果没有排序子句，范围的行为可能不符合预期。 from 和 to 值都是从 0 开始的，包括边界：range(1, 3) 将包含查询的第二、第三和第四行。

参数

fromnumber
限制结果的起始索引
tonumber
限制结果的最后一个索引
optionsobject
命名参数

返回类型

this

1
const { data, error } = await supabase
2
  .from('characters')
3
  .select('name')
4
  .range(0, 1)

设置中止信号

abortSignal(signal)

为 fetch 请求设置 AbortSignal。

您可以使用它为请求设置超时。

参数

signalAbortSignal
用于 fetch 请求的 AbortSignal

返回类型

this

1
const ac = new AbortController()
2
ac.abort()
3
const { data, error } = await supabase
4
  .from('very_big_table')
5
  .select()
6
  .abortSignal(ac.signal)

检索一行数据

single()

将 data 作为单个对象而不是对象数组返回。

查询结果必须为一行（例如，使用 .limit(1)），否则将返回错误。

1
const { data, error } = await supabase
2
  .from('characters')
3
  .select('name')
4
  .limit(1)
5
  .single()

检索零行或一行数据

maybeSingle()

将 data 作为单个对象而不是对象数组返回。

查询结果必须为零或一行（例如，使用 .limit(1)），否则将返回错误。

1
const { data, error } = await supabase
2
  .from('characters')
3
  .select()
4
  .eq('name', 'Katniss')
5
  .maybeSingle()

检索为 CSV

csv()

将 data 作为 CSV 格式的字符串返回。

1
const { data, error } = await supabase
2
  .from('characters')
3
  .select()
4
  .csv()

覆盖成功响应的类型

returns()

覆盖返回的 data 的类型。

已弃用：请改用 overrideTypes 方法

1
const { data } = await supabase
2
  .from('countries')
3
  .select()
4
  .returns<Array<MyType>>()

部分覆盖或替换成功响应的类型

overrideTypes()

覆盖响应中返回的 data 字段的类型。

1
const { data } = await supabase
2
  .from('countries')
3
  .select()
4
  .overrideTypes<Array<MyType>, { merge: false }>()

使用 explain

explain(options)

将 data 作为查询的 EXPLAIN 计划返回。

在使用此方法之前，需要启用 db_plan_enabled 设置。

参数

optionsobject
命名参数

返回类型

以下选项之一

Option 1PostgrestBuilder
Option 2PostgrestBuilder

1
const { data, error } = await supabase
2
  .from('characters')
3
  .select()
4
  .explain()

概述

可以通过 supabase.auth 命名空间访问身份验证方法。
默认情况下，supabase 客户端将 persistSession 设置为 true 并尝试将会话存储在本地存储中。当在不支持本地存储的环境中使用 supabase 客户端时，您可能会看到以下警告消息被记录

不存在存储选项来持久化会话，这可能会导致在使用 auth 时出现意外行为。如果您想将 persistSession 设置为 true，请提供一个存储选项，或者您可以将 persistSession 设置为 false 以禁用此警告。

如果您不在服务器端使用 auth，则可以安全地忽略此警告消息。如果您正在使用 auth 并且想要将 persistSession 设置为 true，则需要提供一个遵循此接口的自定义存储实现。
发送的任何电子邮件链接和一次性密码 (OTP) 都有默认的 24 小时有效期。我们有以下速率限制以防止暴力攻击。
访问令牌的有效期可以在您的项目身份验证设置中的“JWT 有效期限制”字段中设置。刷新令牌永不过期，只能使用一次。

1
import { createClient } from '@supabase/supabase-js'
2
3
const supabase = createClient(supabase_url, anon_key)

创建新用户

signUp(credentials)

创建一个新用户。

请注意，如果系统中存在用户帐户，您可能会收到试图向用户隐藏此信息的错误消息。此方法通过电子邮件注册支持 PKCE。启用 autoconfirm 时，无法使用 PKCE 流程。

默认情况下，用户需要在登录前验证其电子邮件地址。要关闭此功能，请在您的项目中禁用 确认电子邮件。
**确认电子邮件** 确定用户在注册后是否需要确认其电子邮件地址。
- 如果启用了 **确认电子邮件**，则会返回一个 `user`，但 `session` 为 null。
- 如果禁用了 **确认电子邮件**，则会同时返回 `user` 和 `session`。
当用户确认其电子邮件地址时，他们默认会被重定向到 SITE_URL。您可以在您的项目中修改您的 SITE_URL 或添加其他重定向 URL。
如果对已存在的已确认用户调用 signUp()
- 当在您的项目中同时启用 **确认电子邮件** 和 **确认电话**（即使电话提供程序已禁用）时，将返回一个混淆/虚假的用户对象。
- 当 **确认电子邮件** 或 **确认电话**（即使电话提供程序已禁用）中的任何一个被禁用时，将返回错误消息 `User already registered`。
要获取当前登录的用户，请参阅 getUser()。

参数

credentialsSignUpWithPasswordCredentials

返回类型

Promise<以下选项之一>

Option 1object
Option 2object

监听认证事件

onAuthStateChange(callback)

在发生任何身份验证事件时收到通知。在没有 async 函数的情况下使用，是安全的。

订阅用户会话中发生的重要事件。
在前端/客户端使用。在服务器上用处较小。
事件会在所有标签页中发出，以使您的应用程序的 UI 保持最新。某些事件可能会根据打开的标签页数量而非常频繁地触发。使用快速高效的回调函数，并将尽可能多的操作延迟或节流到回调函数外部执行。
重要提示： 回调函数可以是 async 函数，并且在导致事件更改的处理过程中同步运行。通过在调用另一个 Supabase 库的方法时使用 await，很容易创建一个死锁。
- 避免将 async 函数用作回调函数。
- 限制 async 回调函数中 await 的数量。
- 不要在回调函数中使用其他 Supabase 函数。如果必须使用，请在回调函数执行完成后分派这些函数。以这种方式快速实现此目的
```
1
supabase.auth.onAuthStateChange((event, session) => {
2
  setTimeout(async () => {
3
    // await on other Supabase function here
4
    // this runs right after the callback has finished
5
  }, 0)
6
})
```
发出的事件
- INITIAL_SESSION
  - 在构造 Supabase 客户端并从存储加载初始会话后立即发出。
- SIGNED_IN
  - 每次确认或重新建立用户会话时发出，包括用户登录和重新聚焦标签页时。
  - 避免假设此事件何时触发，即使用户已经登录也可能发生。请检查附加到事件的用户对象，以查看是否已登录新用户并更新您的应用程序的 UI。
  - 此事件的触发频率取决于应用程序中打开的标签页数量。
- SIGNED_OUT
  - 用户注销时发出。这可能是因为
    - 调用了 supabase.auth.signOut()。
    - 用户的会话因任何原因已过期
      - 用户在另一设备上注销。
      - 会话已达到其时间限制或非活动超时。
      - 用户在启用了每个用户一个会话的情况下，在另一设备上登录。
      - 有关更多信息，请查看用户会话文档。
  - 用于清理应用程序与用户关联的任何本地存储。
- TOKEN_REFRESHED
  - 每次为已登录用户获取新的访问和刷新令牌时发出。
  - 最好提取访问令牌 (JWT) 并将其存储在内存中以供您的应用程序进一步使用。
    - 避免为同一目的频繁调用 supabase.auth.getSession()。
  - 有一个后台进程跟踪应该刷新会话的时间，因此您始终会通过收听此事件接收有效的令牌。
  - 此事件的频率与项目中配置的 JWT 有效期限制有关。
- USER_UPDATED
  - 每次成功执行 supabase.auth.updateUser() 方法时发出。侦听它以根据新的个人资料信息更新您的应用程序的 UI。
- PASSWORD_RECOVERY
  - 在用户访问包含密码恢复链接的 URL 的页面时，而不是 SIGNED_IN 事件触发。
  - 用于向用户显示一个用户界面，让他们可以重置密码。

参数

回调函数函数
当发生身份验证事件时要调用的回调函数。

返回类型

object

1
const { data } = supabase.auth.onAuthStateChange((event, session) => {
2
  console.log(event, session)
3
4
  if (event === 'INITIAL_SESSION') {
5
    // handle initial session
6
  } else if (event === 'SIGNED_IN') {
7
    // handle sign in event
8
  } else if (event === 'SIGNED_OUT') {
9
    // handle sign out event
10
  } else if (event === 'PASSWORD_RECOVERY') {
11
    // handle password recovery event
12
  } else if (event === 'TOKEN_REFRESHED') {
13
    // handle token refreshed event
14
  } else if (event === 'USER_UPDATED') {
15
    // handle user updated event
16
  }
17
})
18
19
// call unsubscribe to remove the callback
20
data.subscription.unsubscribe()

创建匿名用户

signInAnonymously(credentials?)

创建一个新的匿名用户。

返回一个匿名用户
建议为匿名注册设置验证码以防止滥用。您可以在 `options` 参数中传递验证码令牌。

参数

credentials
可选
SignInAnonymouslyCredentials

返回类型

Promise<以下选项之一>

Option 1object
Option 2object

登录用户

signInWithPassword(credentials)

使用电子邮件和密码或电话和密码登录现有用户。

请注意，您可能会收到一个错误消息，该消息无法区分帐户不存在、电子邮件/电话和密码组合错误或帐户只能通过社交登录访问的情况。

需要电子邮件和密码或电话号码和密码。

参数

credentialsSignInWithPasswordCredentials

返回类型

Promise<以下选项之一>

Option 1object
Option 2object

使用 ID Token 登录 (原生登录)

signInWithIdToken(credentials)

允许使用 OIDC ID 令牌进行登录。使用的身份验证提供程序应已启用并配置。

使用 ID 令牌登录。
在移动或桌面应用程序中使用 Sign in with Apple 或 Sign in with Google 在 iOS 和 Android 上实现登录时特别有用。
您还可以通过此 API 使用 Google 的 One Tap 和自动登录。

参数

credentialsSignInWithIdTokenCredentials

返回类型

Promise<以下选项之一>

Option 1object
Option 2object

通过 OTP 登录用户

signInWithOtp(credentials)

使用 magiclink 或一次性密码 (OTP) 登录用户。

如果在电子邮件模板中指定了 {{ .ConfirmationURL }} 变量，则会发送 magiclink。如果在电子邮件模板中指定了 {{ .Token }} 变量，则会发送 OTP。如果您使用的是电话登录，则只会发送 OTP。您无法为电话登录发送 magiclink。

请注意，您可能会收到一个错误消息，该消息无法区分帐户不存在或帐户只能通过社交登录访问的情况。

请注意，如果您使用 'whatsapp' 频道进行电话登录，则需要配置 Twilio 上的 Whatsapp 发送者。目前其他提供商不支持 whatsapp 频道。这种方法在传递电子邮件时支持 PKCE。

需要电子邮件或电话号码。
此方法用于无密码登录，其中 OTP 会发送到用户的电子邮件或电话号码。
如果用户不存在，signInWithOtp() 将注册用户。要限制此行为，您可以将 SignInWithPasswordlessCredentials.options 中的 shouldCreateUser 设置为 false。
如果您使用的是电子邮件，您可以配置是否希望用户接收 magiclink 或 OTP。
如果您使用的是电话，您可以配置是否希望用户接收 OTP。
magic link 的目标 URL 由 SITE_URL 确定。
请参阅重定向 URL 和通配符，以将其他重定向 URL 添加到您的项目中。
magic link 和 OTP 共享相同的实现。要向用户发送一次性代码而不是 magic link，修改 magic link 电子邮件模板以包含 {{ .Token }} 而不是 {{ .ConfirmationURL }}。
请参阅我们的 Twilio 电话身份验证指南，了解有关配置 WhatsApp 登录的详细信息。

参数

credentials以下选项之一
- Option 1object
- Option 2object

返回类型

Promise<以下选项之一>

Option 1object
Option 2object

通过 OAuth 登录用户

signInWithOAuth(credentials)

通过第三方提供商登录现有用户。此方法支持 PKCE 流程。

此方法用于使用社交登录 (OAuth) 提供商登录。
它的工作原理是将您的应用程序重定向到提供商的授权屏幕，然后再将用户带回到您的应用程序。

参数

credentialsSignInWithOAuthCredentials

返回类型

Promise<以下选项之一>

Option 1object
Option 2object

通过 SSO 登录用户

signInWithSSO(params)

尝试使用企业身份提供商进行单点登录。成功的 SSO 尝试会将当前页面重定向到身份提供商授权页面。重定向 URL 取决于实现和 SSO 协议。

您可以通过提供 SSO 域来使用它。通常，您可以要求用户提供他们的电子邮件地址来提取此域。如果此域在 Auth 实例上注册，则重定向将使用该组织的当前活动的 SSO 身份提供商进行登录。

如果您构建了特定于组织的登录页面，可以直接使用该组织的 SSO 身份提供商 UUID。

在您可以使用此方法之前，您需要建立与身份提供程序的连接。使用 CLI 命令来执行此操作。
如果您已将电子邮件域与身份提供程序关联，则可以使用 `domain` 属性启动登录流程。
如果您需要使用不同的方式使用身份提供程序启动身份验证流程，可以使用 `providerId` 属性。例如
- 将特定的用户电子邮件地址与身份提供程序映射。
- 使用不同的提示来识别用户要使用的身份提供程序，例如公司特定的页面、IP 地址或其他跟踪信息。

参数

params以下选项之一
- Option 1object
- Option 2object

返回类型

Promise<以下选项之一>

Option 1object
Option 2object

1
// You can extract the user's email domain and use it to trigger the
2
  // authentication flow with the correct identity provider.
3
4
  const { data, error } = await supabase.auth.signInWithSSO({
5
    domain: 'company.com'
6
  })
7
8
  if (data?.url) {
9
    // redirect the user to the identity provider's authentication flow
10
    window.location.href = data.url
11
  }

通过 Web3 (Solana, Ethereum) 登录用户

signInWithWeb3(credentials)

通过验证用户私钥签名的消息来登录用户。支持以太坊（通过 Sign-In-With-Ethereum）和 Solana（Sign-In-With-Solana）标准，两者都源自 EIP-4361 标准，Solana 方面略有变化。

使用 Web3（以太坊、Solana）钱包登录用户。
在将其用于之前，请阅读有关潜在滥用的内容。

参数

credentials以下选项之一
- 选项 1以下选项之一
  Option 1object
  Option 2object
- 选项 2以下选项之一
  Option 1object
  Option 2object

返回类型

Promise<以下选项之一>

Option 1object
Option 2object

1
// uses window.ethereum for the wallet
2
  const { data, error } = await supabase.auth.signInWithWeb3({
3
    chain: 'ethereum',
4
    statement: 'I accept the Terms of Service at https://example.com/tos'
5
  })
6
7
  // uses window.solana for the wallet
8
  const { data, error } = await supabase.auth.signInWithWeb3({
9
    chain: 'solana',
10
    statement: 'I accept the Terms of Service at https://example.com/tos'
11
  })

从经过验证的 JWT 获取用户声明

getClaims(jwt?, options)

通过首先在服务器的 JSON Web Key Set 端点 /.well-known/jwks.json（通常会缓存）上验证 JWT 来提取访问令牌中存在的 JWT 声明。优选此方法而不是 #getUser，后者始终将请求发送到 Auth 服务器以获取每个 JWT。

如果项目未使用非对称 JWT 签名密钥（如 ECC 或 RSA），它始终会发送请求到 Auth 服务器（类似于 #getUser）以验证 JWT。

解析用户的访问令牌作为 JSON Web Token (JWT)，如果有效且未过期，则返回其组件。
如果您的项目使用非对称 JWT 签名密钥，则通常使用 WebCrypto API 在本地进行验证，通常无需网络请求。
会向您的项目 JWT 签名密钥发现端点 https://project-id.supabase.co/auth/v1/.well-known/jwks.json 发送网络请求，并在本地缓存。如果您的环境是短暂的，例如在每次请求后都会销毁的 Lambda 函数，则每次新调用都会发送网络请求。Supabase 提供网络边缘缓存，为这些情况提供快速响应。
如果用户的访问令牌在调用此函数时即将过期，则首先会刷新用户的会话，然后再验证 JWT。
如果您的项目使用对称密钥对 JWT 进行签名，它始终会发送类似于 getUser() 的请求，以在服务器上验证 JWT，然后再返回解码的令牌。如果环境中不可用 WebCrypto API，也使用此方法。在这种情况下，请确保对其进行多态填充。
返回的声明可以使用自定义访问令牌 Hook 为每个项目进行自定义。

参数

jwt
可选
字符串
您希望验证的特定 JWT（可选），而不是您可以从 #getSession 获取的 JWT。
optionsobject
各种其他选项，允许您自定义此方法行为。

返回类型

Promise<以下选项之一>

Option 1object
Option 2object
选项 3对象

1
const { data, error } = await supabase.auth.getClaims()

注销用户

signOut(options)

在浏览器上下文中，signOut() 将从浏览器会话中删除已登录用户并注销他们 - 删除 localstorage 中的所有项目，然后触发 "SIGNED_OUT" 事件。

对于服务器端管理，您可以将用户的 JWT 传递给 auth.api.signOut(JWT: string) 来撤销用户的所有刷新令牌。在 JWT 过期之前，无法撤销用户的访问令牌 jwt。因此，建议为 jwt 设置较短的过期时间。

如果使用 others 范围，则不会触发 SIGNED_OUT 事件！

为了使用 `signOut()` 方法，用户需要先登录。
默认情况下，signOut() 使用全局范围，这会注销用户登录的所有其他会话。通过传递范围参数来自定义此行为。
由于 Supabase Auth 使用 JWT 进行身份验证，因此访问令牌 JWT 在其过期之前有效。当用户注销时，Supabase 撤销刷新令牌并从客户端删除 JWT。这不会撤销 JWT，并且它在过期之前仍然有效。

参数

optionsSignOut

返回类型

Promise<object>

1
const { error } = await supabase.auth.signOut()

发送密码重置请求

resetPasswordForEmail(email, options)

向电子邮件地址发送密码重置请求。此方法支持 PKCE 流程。

密码重置流程包含 2 个主要步骤：(i) 允许用户通过密码重置链接登录；(ii) 更新用户的密码。
resetPasswordForEmail() 仅将密码重置链接发送到用户的电子邮件。要更新用户的密码，请参阅 updateUser()。
当用户单击密码恢复链接时，将发出 PASSWORD_RECOVERY 事件。您可以使用 onAuthStateChange() 侦听并在这些事件上调用回调函数。
当用户单击电子邮件中的重置链接时，他们会被重定向回您的应用程序。您可以使用 redirectTo 参数配置用户重定向到的 URL。请参阅重定向 URL 和通配符，以将其他重定向 URL 添加到您的项目中。
用户成功重定向后，提示他们输入新密码并调用 updateUser()

1
const { data, error } = await supabase.auth.updateUser({
2
  password: new_password
3
})

参数

email字符串
用户的电子邮件地址。
optionsobject

返回类型

Promise<以下选项之一>

Option 1object
Option 2object

1
const { data, error } = await supabase.auth.resetPasswordForEmail(email, {
2
  redirectTo: 'https://example.com/update-password',
3
})

通过 OTP 验证并登录

verifyOtp(params)

使用用户提供的 OTP 或通过移动设备或电子邮件收到的 TokenHash 登录用户。

verifyOtp 方法接受不同的验证类型。
如果使用电话号码，则类型可以是
1. sms – 用于在注册或登录期间通过短信验证一次性密码 (OTP)。
2. phone_change – 用于在电话号码更新过程中验证发送到新电话号码的 OTP。
如果使用电子邮件地址，则类型可以是以下之一（请注意：signup 和 magiclink 类型已弃用）
1. email – 用于在注册或登录期间验证发送到用户电子邮件的 OTP。
2. recovery – 用于在帐户恢复后（通常是在密码重置请求之后）验证发送的 OTP。
3. invite – 用于验证作为加入项目或组织的邀请的一部分发送的 OTP。
4. email_change – 用于验证在电子邮件更新过程中发送到新电子邮件地址的 OTP。
应根据在调用 verifyOtp 注册/登录用户之前调用的相应身份验证方法来确定使用的验证类型。
TokenHash 包含在电子邮件模板中，可用于登录。您可能希望将哈希用于服务器端身份验证的 PKCE 流程。请阅读基于密码的身份验证指南以获取更多详细信息。

参数

params以下选项之一
- 选项 1VerifyMobileOtpParams
- 选项 2VerifyEmailOtpParams
- 选项 3VerifyTokenHashParams

返回类型

Promise<以下选项之一>

Option 1object
Option 2object

获取会话

getSession()

返回会话，如果需要则刷新它。

如果未检测到会话（例如，用户未登录或已注销），则返回的会话可能为空。

重要提示： 此方法直接从附加到客户端的存储中加载值。如果该存储基于请求 cookie，例如，那么其中的值可能不真实，因此强烈建议不要在此类情况下使用此方法及其结果。如果检测到这种情况，将发出警告。请改用 #getUser()。

自从引入非对称 JWT 签名密钥以来，此方法被认为是低级方法，我们鼓励您改用 getClaims() 或 getUser()。
从存储介质（本地存储、cookie）检索当前的用户会话。
会话包含访问令牌（签名 JWT）、刷新令牌和用户对象。
如果会话的访问令牌已过期或即将过期，此方法将使用刷新令牌来刷新会话。
在浏览器中使用时，或者在您的环境中调用了 startAutoRefresh()（React Native 等），此函数始终返回有效的访问令牌，而无需刷新会话本身，因为这在后台完成。此函数返回速度非常快。
重要安全提示： 如果使用不安全的存储介质，例如 cookie 或请求标头，则此函数返回的用户对象 不可信任。始终使用 getClaims() 或您自己的 JWT 验证库来安全地建立用户的身份和访问权限。您还可以使用 getUser() 从 Auth 服务器直接获取用户对象以达到此目的。
在浏览器中使用时，此函数使用 LockManager API 在所有选项卡中同步。在其他环境中，请确保您已定义适当的 lock 属性（如果需要），以确保在刷新会话时没有竞争条件。

返回类型

Promise<以下选项之一>

Option 1object
Option 2object
选项 3对象

1
const { data, error } = await supabase.auth.getSession()

获取新的会话

refreshSession(currentSession?)

返回新的会话，无论其过期状态如何。接受可选的当前会话。如果未传入，则 refreshSession() 将尝试从 getSession() 中检索它。如果当前会话的刷新令牌无效，将抛出错误。

此方法将刷新并返回新的会话，无论当前会话是否已过期。

参数

currentSession
可选
object
当前会话。如果传入，则必须包含刷新令牌。

返回类型

Promise<以下选项之一>

Option 1object
Option 2object

1
const { data, error } = await supabase.auth.refreshSession()
2
const { session, user } = data

获取用户

getUser(jwt?)

如果存在会话，则获取当前用户详细信息。此方法向 Supabase Auth 服务器发出网络请求，因此返回的值是真实的，可用于基于此制定授权规则。

此方法从数据库而不是本地会话中获取用户对象。
此方法对于检查用户是否已授权很有用，因为它会在服务器上验证用户的访问令牌 JWT。
在服务器上检查用户授权时，应始终使用此方法。在客户端，您可以改用 getSession().session.user 以获得更快的速度。getSession 在服务器上是不安全的。

参数

jwt
可选
字符串
接受可选的访问令牌 JWT。如果未提供 JWT，则使用当前会话中的 JWT。

返回类型

Promise<以下选项之一>

Option 1object
Option 2object

1
const { data: { user } } = await supabase.auth.getUser()

更新用户

updateUser(attributes, options)

更新已登录用户的用户数据。

为了使用 `updateUser()` 方法，用户需要先登录。
默认情况下，电子邮件更新会将确认链接发送到用户的当前电子邮件和新电子邮件。要仅将确认链接发送到用户的新的电子邮件，请在您项目的电子邮件身份验证提供程序设置中禁用 安全电子邮件更改。

参数

attributesUserAttributes
optionsobject

返回类型

Promise<以下选项之一>

Option 1object
Option 2object

1
const { data, error } = await supabase.auth.updateUser({
2
  email: 'new@email.com'
3
})

获取与用户关联的身份

getUserIdentities()

获取链接到用户的所有身份。

用户需要登录才能调用 getUserIdentities()。

返回类型

Promise<以下选项之一>

Option 1object
Option 2object

1
const { data, error } = await supabase.auth.getUserIdentities()

将身份与用户关联

linkIdentity(credentials)

将 OAuth 身份链接到现有用户。此方法支持 PKCE 流程。

必须从您的项目身份验证设置中启用 **启用手动链接** 选项。
需要先登录才能调用 `linkIdentity()`。
如果候选身份已链接到现有用户或另一个用户，`linkIdentity()` 将失败。
如果在浏览器中运行 linkIdentity，则用户会自动重定向到返回的 URL。在服务器上，您应该处理重定向。

参数

credentials以下选项之一
- 选项 1SignInWithOAuthCredentials
- 选项 2SignInWithIdTokenCredentials

返回类型

Promise<以下选项之一>

Option 1object
Option 2object

1
const { data, error } = await supabase.auth.linkIdentity({
2
  provider: 'github'
3
})

将身份从用户取消关联

unlinkIdentity(identity)

通过删除身份将其从用户处取消链接。用户取消链接后将无法使用该身份登录。

必须从您的项目身份验证设置中启用 **启用手动链接** 选项。
用户需要已登录才能调用 unlinkIdentity()。
用户必须至少拥有 2 个身份才能取消关联一个身份。
要取消关联的身份必须属于该用户。

参数

identityUserIdentity

返回类型

Promise<以下选项之一>

Option 1object
Option 2object

1
// retrieve all identities linked to a user
2
const identities = await supabase.auth.getUserIdentities()
3
4
// find the google identity
5
const googleIdentity = identities.find(
6
  identity => identity.provider === 'google'
7
)
8
9
// unlink the google identity
10
const { error } = await supabase.auth.unlinkIdentity(googleIdentity)

发送密码重新认证 nonce

reauthenticate()

向用户的电子邮件或电话号码发送重新身份验证 OTP。需要用户已登录。

当需要更新用户的密码时，此方法与 updateUser() 结合使用。
如果您要求用户在更新密码之前重新进行身份验证，则需要在您的项目电子邮件提供程序设置中启用 安全密码更改 选项。
如果启用了 安全密码更改 并且用户 最近未登录，则仅需要在更新密码之前重新身份验证。如果会话在过去 24 小时内创建，则认为用户最近已登录。
此方法会将 nonce 发送到用户的电子邮件。如果用户没有确认的电子邮件地址，该方法会将 nonce 发送到用户的确认的电话号码。
收到 OTP 后，请在 updateUser() 调用中将其作为 nonce 包含，以完成密码更改。

返回类型

Promise<以下选项之一>

Option 1object
Option 2object

1
const { error } = await supabase.auth.reauthenticate()

重新发送 OTP

resend(credentials)

重新发送现有的注册确认电子邮件、电子邮件更改电子邮件、短信 OTP 或电话号码更改 OTP。

通过再次调用 reset_password_for_email() 方法，可以重新发送密码重置电子邮件。
可以通过再次调用 signInWithOtp() 方法来重新发送无密码登录。
可以通过再次调用 resetPasswordForEmail() 方法重新发送密码恢复电子邮件。
此方法仅会在正在进行初始注册、电子邮件更改或电话号码更改请求时，才会重新发送电子邮件或电话 OTP（注意：对于使用 OTP 登录的现有用户，您应该再次使用 signInWithOtp() 来重新发送 OTP）。
您可以使用 emailRedirectTo 选项在重新发送电子邮件链接时指定重定向 URL。

参数

credentials以下选项之一
- Option 1object
- Option 2object

返回类型

Promise<以下选项之一>

Option 1object
Option 2object

设置会话数据

setSession(currentSession)

从当前会话设置会话数据。如果当前会话已过期，setSession 将负责刷新它以获取新的会话。如果当前会话中的刷新令牌或访问令牌无效，将抛出错误。

此方法使用 access_token 和 refresh_token 设置会话。
如果成功，将发出 SIGNED_IN 事件。

参数

currentSessionobject
当前会话，至少包含访问令牌和刷新令牌。

返回类型

Promise<以下选项之一>

Option 1object
Option 2object

1
const { data, error } = await supabase.auth.setSession({
2
    access_token,
3
    refresh_token
4
  })

将授权码交换为会话

exchangeCodeForSession(authCode)

通过在 PKCE 流程期间发出的授权码登录现有用户。

当客户端选项中的 flowType 设置为 pkce 时使用。

参数

authCodestring

返回类型

Promise<以下选项之一>

Option 1object
Option 2object

1
supabase.auth.exchangeCodeForSession('34e770dd-9ff9-416c-87fa-43b31d7ef225')

启动自动刷新会话 (非浏览器)

startAutoRefresh()

在后台启动自动刷新流程。会话每隔几秒钟检查一次。接近到期时间时，将启动一个流程来刷新会话。如果刷新失败，将持续重试，直到成功为止。

如果您设置了 GoTrueClientOptions#autoRefreshToken，则不需要调用此函数，它将为您调用。

在浏览器中，刷新过程仅在选项卡/窗口处于前景时才有效，以节省资源并防止竞争条件和向身份验证服务器发送大量请求。如果您调用此方法，任何管理的可见性更改回调都将被删除，并且您必须自行管理可见性更改。

在非浏览器平台上，刷新过程持续在后台工作，这可能不是您想要的。您应该连接到平台的显示指示机制，并适当地调用这些方法以节省资源。

#stopAutoRefresh

仅在非浏览器环境（例如 React Native 或 Electron）中才有用。
Supabase Auth 库会自动启动和停止主动刷新会话，当选项卡处于焦点或非焦点状态时。
在非浏览器平台上，该库无法有效地确定应用程序是否处于焦点状态。
为了向应用程序提供此提示，您应该在应用程序处于焦点状态时调用此方法，并在应用程序失去焦点状态时调用 supabase.auth.stopAutoRefresh()。

返回类型

Promise<void>

1
import { AppState } from 'react-native'
2
3
// make sure you register this only once!
4
AppState.addEventListener('change', (state) => {
5
  if (state === 'active') {
6
    supabase.auth.startAutoRefresh()
7
  } else {
8
    supabase.auth.stopAutoRefresh()
9
  }
10
})

停止自动刷新会话 (非浏览器)

stopAutoRefresh()

停止在后台运行的活动自动刷新流程（如果有）。

如果您调用此方法，任何管理的可见性更改回调都将被删除，并且您必须自行管理可见性更改。

有关更多详细信息，请参阅 #startAutoRefresh。

仅在非浏览器环境（例如 React Native 或 Electron）中才有用。
Supabase Auth 库会自动启动和停止主动刷新会话，当选项卡处于焦点或非焦点状态时。
在非浏览器平台上，该库无法有效地确定应用程序是否处于焦点状态。
当您的应用程序进入后台或失去焦点时，请调用此方法以停止会话的自动刷新。

返回类型

Promise<void>

1
import { AppState } from 'react-native'
2
3
// make sure you register this only once!
4
AppState.addEventListener('change', (state) => {
5
  if (state === 'active') {
6
    supabase.auth.startAutoRefresh()
7
  } else {
8
    supabase.auth.stopAutoRefresh()
9
  }
10
})

初始化客户端会话

initialize()

从 URL 或存储初始化客户端会话。此方法在实例化客户端时会自动调用，但还应在检查来自身份验证重定向（OAuth、magiclink、密码恢复等）的错误时手动调用。

返回类型

Promise<InitializeResult>

认证 MFA

本节包含通常用于多因素身份验证 (MFA) 的方法，并在 supabase.auth.mfa 命名空间下调用。

目前，支持基于时间的一次性密码 (TOTP) 和电话验证码作为第二因素。不支持恢复代码，但用户可以注册多个因素，上限为 10 个。

拥有用于恢复的第二因素可以减轻用户存储恢复代码的负担。它还可以减少攻击面，因为通常会生成多个恢复代码，而不是只有一个备份因素。

了解更多关于在您的应用程序中实施 MFA 的信息在 MFA 指南中。

注册因素

enroll(params)

启动新的多因素身份验证 (MFA) 因素的注册流程。此方法创建一个新的未验证因素。要验证一个因素，请向用户展示二维码或密钥，并要求他们将其添加到身份验证器应用程序中。用户必须输入身份验证器应用程序中的代码来验证它。

验证一个因素后，所有其他会话将被注销，并且当前会话的身份验证器级别提升到 aal2。

使用 totp 或 phone 作为 factorType，并使用返回的 id 创建一个挑战。
要创建挑战，请参阅 mfa.challenge()。
要验证挑战，请参阅 mfa.verify()。
要一步创建和验证 TOTP 挑战，请参阅 mfa.challengeAndVerify()。
要在 Next.js 中为 totp 密钥生成二维码，您可以执行以下操作

1
<Image src={data.totp.qr_code} alt={data.totp.uri} layout="fill"></Image>

当使用电话因素时，challenge 和 verify 步骤是分开的，因为用户需要时间来接收并输入通过短信获得的验证码。

参数

params以下选项之一
- Option 1object
- Option 2object
- 选项 3对象
- 选项 4MFAEnrollTOTPParams
- 选项 5MFAEnrollPhoneParams
- 选项 6MFAEnrollWebauthnParams

返回类型

Promise<以下选项之一>

Option 1object
Option 2object

1
const { data, error } = await supabase.auth.mfa.enroll({
2
  factorType: 'totp',
3
  friendlyName: 'your_friendly_name'
4
})
5
6
// Use the id to create a challenge.
7
// The challenge can be verified by entering the code generated from the authenticator app.
8
// The code will be generated upon scanning the qr_code or entering the secret into the authenticator app.
9
const { id, type, totp: { qr_code, secret, uri }, friendly_name } = data
10
const challenge = await supabase.auth.mfa.challenge({ factorId: id });

创建挑战

challenge(params)

准备一个挑战，用于验证用户是否可以访问 MFA 因素。

在创建挑战之前，需要一个已注册的因素。
要验证挑战，请参阅 mfa.verify()。
电话因素在挑战时向用户发送验证码。渠道默认为 sms，除非另有说明。

参数

params以下选项之一
- Option 1object
- Option 2object
- 选项 3对象
- 选项 4MFAChallengeTOTPParams
- 选项 5MFAChallengePhoneParams
- 选项 6MFAChallengeWebauthnParams

返回类型

Promise<以下选项之一>

Option 1object
Option 2object

1
const { data, error } = await supabase.auth.mfa.challenge({
2
  factorId: '34e770dd-9ff9-416c-87fa-43b31d7ef225'
3
})

验证挑战

verify(params)

验证代码与挑战是否匹配。验证码由用户输入身份验证器应用程序中看到的代码提供。

要验证挑战，请先创建挑战。

参数

params以下选项之一
- Option 1object
- Option 2object
- 选项 3MFAVerifyTOTPParams
- 选项 4MFAVerifyPhoneParams
- 选项 5MFAVerifyWebauthnParams

返回类型

Promise<以下选项之一>

Option 1object
Option 2object

1
const { data, error } = await supabase.auth.mfa.verify({
2
  factorId: '34e770dd-9ff9-416c-87fa-43b31d7ef225',
3
  challengeId: '4034ae6f-a8ce-4fb5-8ee5-69a5863a7c15',
4
  code: '123456'
5
})

创建并验证挑战

challengeAndVerify(params)

辅助方法，用于创建挑战并立即使用给定的代码对其进行验证。验证码由用户输入身份验证器应用程序中看到的代码提供。

仅供 TOTP 因素使用。
在调用 challengeAndVerify() 之前，需要一个已注册的因素。
在一个步骤中执行 mfa.challenge() 和 mfa.verify()。

参数

paramsobject

返回类型

Promise<以下选项之一>

Option 1object
Option 2object

1
const { data, error } = await supabase.auth.mfa.challengeAndVerify({
2
  factorId: '34e770dd-9ff9-416c-87fa-43b31d7ef225',
3
  code: '123456'
4
})

取消注册因素

unenroll(params)

注销会删除 MFA 因素。用户必须具有 aal2 身份验证器级别才能注销 已验证 因素。

参数

paramsMFAUnenrollParams

返回类型

Promise<以下选项之一>

Option 1object
Option 2object

1
const { data, error } = await supabase.auth.mfa.unenroll({
2
  factorId: '34e770dd-9ff9-416c-87fa-43b31d7ef225',
3
})

获取身份验证器保证级别

getAuthenticatorAssuranceLevel(jwt?)

返回活动会话的身份验证器保证级别 (AAL)。

aal1 (或 null) 表示用户的身份仅通过传统的登录方式（电子邮件+密码、OTP、魔法链接、社交登录等）进行验证。
aal2 表示用户的身份已通过传统的登录方式和至少一个 MFA 因素进行验证。

如果不提供 JWT 参数调用此方法，则该方法速度很快（微秒级）并且很少使用网络。如果提供了 JWT（在边缘函数等服务器端环境中很有用，因为没有存储会话），该方法将发出网络请求以验证用户并获取他们的 MFA 因素。

身份验证器保证级别 (AAL) 是身份验证机制强度的度量。
在 Supabase 中，具有 aal1 AAL 表示具有第一因素身份验证，例如电子邮件和密码或 OAuth 登录，而 aal2 表示第二因素身份验证，例如基于时间的、一次性密码 (TOTP) 或电话因素。
如果用户具有已验证的因素，则 nextLevel 字段将返回 aal2，否则，将返回 aal1。
可以传递一个可选的 jwt 参数来检查特定 JWT 的 AAL 级别，而不是当前会话。

参数

jwt
可选
字符串
要检查 AAL 级别的可选 JWT。如果未提供，则使用当前会话的 JWT。

返回类型

Promise<以下选项之一>

Option 1object
Option 2object

1
const { data, error } = await supabase.auth.mfa.getAuthenticatorAssuranceLevel()
2
const { currentLevel, nextLevel, currentAuthenticationMethods } = data

列出当前用户的所有因素

listFactors()

返回为此用户启用的 MFA 因素列表。

返回类型

Promise<以下选项之一>

Option 1object
Option 2object

OAuth 服务器

OAuth 服务器 API 允许您为应用程序构建自定义 OAuth 同意屏幕。仅当在 Supabase Auth 中启用 OAuth 2.1 服务器时才相关。

获取授权详细信息

getAuthorizationDetails(authorizationId)

检索 OAuth 授权请求的详细信息。用于向用户显示同意信息。仅当在 Supabase Auth 中启用 OAuth 2.1 服务器时才相关。

此方法返回以下两种响应类型之一

OAuthAuthorizationDetails：用户需要同意 - 显示带有客户端信息的同意页面
OAuthRedirect：用户已同意 - 立即重定向到 OAuth 客户端

使用类型缩小来区分响应

1
if ('authorization_id' in data) {
2
  // Show consent page
3
} else {
4
  // Redirect to data.redirect_url
5
}

参数

authorizationIdstring
来自授权请求的授权 ID

返回类型

Promise<以下选项之一>

Option 1object
Option 2object

批准授权

approveAuthorization(authorizationId, options?)

批准 OAuth 授权请求。仅当在 Supabase Auth 中启用 OAuth 2.1 服务器时才相关。

批准后，用户的同意将被存储，并生成一个带有授权代码和状态的完整重定向 URL。

参数

authorizationIdstring
要批准的授权 ID
options
可选
object
可选参数

返回类型

Promise<以下选项之一>

Option 1object
Option 2object

拒绝授权

denyAuthorization(authorizationId, options?)

拒绝 OAuth 授权请求。仅当在 Supabase Auth 中启用 OAuth 2.1 服务器时才相关。

拒绝后，响应将包含一个带有 OAuth 错误 (access_denied) 的重定向 URL，以告知 OAuth 客户端用户拒绝了请求。

参数

authorizationIdstring
要拒绝的授权 ID
options
可选
object
可选参数

返回类型

Promise<以下选项之一>

Option 1object
Option 2object

列出授权

listGrants()

列出经过身份验证的用户授权的所有 OAuth 授权。仅当在 Supabase Auth 中启用 OAuth 2.1 服务器时才相关。

返回类型

Promise<以下选项之一>

Option 1object
Option 2object

撤销授权

revokeGrant(options)

撤销用户对特定客户端的 OAuth 授权。仅当在 Supabase Auth 中启用 OAuth 2.1 服务器时才相关。

撤销会将同意标记为已撤销，删除该 OAuth 客户端的活动会话，并使相关的刷新令牌失效。

参数

optionsobject
撤销选项

返回类型

Promise<以下选项之一>

Option 1object
Option 2object

认证 Admin

supabase.auth.admin 命名空间下的任何方法都需要一个 service_role 密钥。
这些方法被认为是管理方法，应在受信任的服务器上调用。切勿在浏览器中公开你的 service_role 密钥。

1
import { createClient } from '@supabase/supabase-js'
2
3
const supabase = createClient(supabase_url, service_role_key, {
4
  auth: {
5
    autoRefreshToken: false,
6
    persistSession: false
7
  }
8
})
9
10
// Access auth admin api
11
const adminAuthClient = supabase.auth.admin

获取用户

getUserById(uid)

通过 ID 获取用户。

根据用户的 ID 从数据库中获取用户对象。
getUserById() 方法需要用户的 ID，该 ID 映射到 auth.users.id 列。

参数

uidstring
用户的唯一标识符

此函数只能在服务器上调用。切勿在浏览器中公开您的 service_role 密钥。

返回类型

Promise<以下选项之一>

Option 1object
Option 2object

1
const { data, error } = await supabase.auth.admin.getUserById(1)

列出所有用户

listUsers(params?)

获取用户列表。

此函数只能在服务器上调用。切勿在浏览器中公开您的 service_role 密钥。

默认情况下，每页返回 50 个用户。

参数

params
可选
PageParams
一个对象，支持使用数字 page 和 perPage，以更改分页结果。

返回类型

Promise<以下选项之一>

Option 1object
Option 2object

1
const { data: { users }, error } = await supabase.auth.admin.listUsers()

创建用户

createUser(attributes)

创建新用户。此函数只能在服务器上调用。切勿在浏览器中公开您的 service_role 密钥。

要确认用户的电子邮件地址或电话号码，请将 email_confirm 或 phone_confirm 设置为 true。两个参数都默认为 false。
createUser() 不会向用户发送确认电子邮件。如果您想向他们发送电子邮件邀请，可以使用 inviteUserByEmail()。
如果您确定创建用户的电子邮件或电话号码是合法的且经过验证的，则可以将 email_confirm 或 phone_confirm 参数设置为 true。

参数

attributesAdminUserAttributes

返回类型

Promise<以下选项之一>

Option 1object
Option 2object

1
const { data, error } = await supabase.auth.admin.createUser({
2
  email: 'user@email.com',
3
  password: 'password',
4
  user_metadata: { name: 'Yoda' }
5
})

删除用户

deleteUser(id, shouldSoftDelete)

删除用户。需要 service_role 密钥。

deleteUser() 方法需要用户的 ID，它映射到 auth.users.id 列。

参数

idstring
您要删除的用户 ID。
shouldSoftDeleteboolean
如果为 true，则用户将从 auth 模式中软删除。软删除允许从哈希的用户 ID 识别用户，但不可逆转。默认值为 false，以保持向后兼容性。

此函数只能在服务器上调用。切勿在浏览器中公开您的 service_role 密钥。

返回类型

Promise<以下选项之一>

Option 1object
Option 2object

1
const { data, error } = await supabase.auth.admin.deleteUser(
2
  '715ed5db-f090-4b8c-a067-640ecee36aa0'
3
)

发送电子邮件邀请链接

inviteUserByEmail(email, options)

向电子邮件地址发送邀请链接。

向用户的电子邮件地址发送邀请链接。
inviteUserByEmail() 方法通常由管理员用于邀请用户加入应用程序。
请注意，使用 inviteUserByEmail 不支持 PKCE。这是因为发起邀请的浏览器通常与接受邀请的浏览器不同，这使得提供 PKCE 流所需的安全性保证变得困难。

参数

email字符串
用户的电子邮件地址。
optionsobject
要包含在邀请中的其他选项。

返回类型

Promise<以下选项之一>

Option 1object
Option 2object

1
const { data, error } = await supabase.auth.admin.inviteUserByEmail('email@example.com')

生成电子邮件链接

generateLink(params)

生成要通过自定义电子邮件提供程序发送的电子邮件链接和 OTP。

以下类型可以传递到 generateLink()：signup、magiclink、invite、recovery、email_change_current、email_change_new、phone_change。
如果您的项目电子邮件身份验证提供程序设置中启用了“安全电子邮件更改”，则 generateLink() 仅为 email_change_email 生成电子邮件链接。
generateLink() 为 signup、invite 和 magiclink 创建用户。

参数

paramsGenerateLinkParams

返回类型

Promise<以下选项之一>

Option 1object
Option 2object

更新用户

updateUserById(uid, attributes)

更新用户数据。更改将直接应用，无需确认流程。

参数

uidstring
用户的唯一标识符
attributesAdminUserAttributes
您要更新的数据。

此函数只能在服务器上调用。切勿在浏览器中公开您的 service_role 密钥。

返回类型

Promise<以下选项之一>

Option 1object
Option 2object

1
const { data: user, error } = await supabase.auth.admin.updateUserById(
2
  '11111111-1111-1111-1111-111111111111',
3
  { email: 'new@email.com' }
4
)

注销用户 (管理员)

signOut(jwt, scope)

删除登录会话。

参数

jwtstring
有效的登录 JWT。
scope以下选项之一
注销范围。
- 选项 1"global"
- 选项 2"local"
- 选项 3"others"

返回类型

Promise<object>

删除用户的因素

deleteFactor(params)

删除用户的一个因素。如果删除的因素已验证，这将使用户退出所有活动会话。

参数

paramsAuthMFAAdminDeleteFactorParams

返回类型

Promise<以下选项之一>

Option 1object
Option 2object

1
const { data, error } = await supabase.auth.admin.mfa.deleteFactor({
2
  id: '34e770dd-9ff9-416c-87fa-43b31d7ef225',
3
  userId: 'a89baba7-b1b7-440f-b4bb-91026967f66b',
4
})

列出用户的全部因素 (管理员)

listFactors(params)

列出与用户关联的所有因素。

参数

paramsAuthMFAAdminListFactorsParams

返回类型

Promise<以下选项之一>

Option 1object
Option 2object

1
const { data, error } = await supabase.auth.admin.mfa.listFactors()

OAuth 管理

OAuth 管理 API 允许您以编程方式管理 OAuth 客户端。仅当在 Supabase Auth 中启用 OAuth 2.1 服务器时才相关。这些函数只能在服务器上调用。切勿在浏览器中公开您的 service_role 密钥。

列出 OAuth 客户端

listClients(params?)

列出所有 OAuth 客户端，并提供可选的分页。仅当在 Supabase Auth 中启用 OAuth 2.1 服务器时才相关。

此函数只能在服务器上调用。切勿在浏览器中公开您的 service_role 密钥。

参数

params
可选
PageParams

返回类型

Promise<以下选项之一>

Option 1object
Option 2object

获取 OAuth 客户端

getClient(clientId)

获取特定的 OAuth 客户端详情。仅当 Supabase Auth 中启用了 OAuth 2.1 服务器时才相关。

此函数只能在服务器上调用。切勿在浏览器中公开您的 service_role 密钥。

参数

clientId字符串

返回类型

Promise<以下选项之一>

Option 1object
Option 2object

创建 OAuth 客户端

createClient(params)

创建新的 OAuth 客户端。仅当 Supabase Auth 中启用了 OAuth 2.1 服务器时才相关。

此函数只能在服务器上调用。切勿在浏览器中公开您的 service_role 密钥。

参数

paramsCreateOAuthClientParams

返回类型

Promise<以下选项之一>

Option 1object
Option 2object

更新 OAuth 客户端

updateClient(clientId, params)

更新现有的 OAuth 客户端。仅当 Supabase Auth 中启用了 OAuth 2.1 服务器时才相关。

此函数只能在服务器上调用。切勿在浏览器中公开您的 service_role 密钥。

参数

clientId字符串
paramsUpdateOAuthClientParams

返回类型

Promise<以下选项之一>

Option 1object
Option 2object

删除 OAuth 客户端

deleteClient(clientId)

删除 OAuth 客户端。仅当 Supabase Auth 中启用了 OAuth 2.1 服务器时才相关。

此函数只能在服务器上调用。切勿在浏览器中公开您的 service_role 密钥。

参数

clientId字符串

返回类型

Promise<object>

重新生成客户端密钥

regenerateClientSecret(clientId)

为 OAuth 客户端重新生成密钥。仅当 Supabase Auth 中启用了 OAuth 2.1 服务器时才相关。

此函数只能在服务器上调用。切勿在浏览器中公开您的 service_role 密钥。

参数

clientId字符串

返回类型

Promise<以下选项之一>

Option 1object
Option 2object

调用 Supabase 边缘函数。

invoke(functionName, options)

调用函数

需要 Authorization 标头。
Invoke 参数通常与 Fetch API 规范相匹配。
当您向函数传递 body 时，我们会自动为 Blob、ArrayBuffer、File、FormData 和 String 附加 Content-Type header。如果它与这些类型中的任何一个都不匹配，我们会假定 payload 是 json，对其进行序列化并附加 Content-Type header 作为 application/json。您可以通过传递自己的 Content-Type header 来覆盖此行为。
响应会自动解析为 json、blob 和 form-data，具体取决于函数发送的 Content-Type header。默认情况下，响应解析为 text。

参数

functionName字符串
要调用的函数名称。
optionsFunctionInvokeOptions
调用函数的选项。

返回类型

Promise<以下选项之一>

选项 1FunctionsResponseSuccess
选项 2FunctionsResponseFailure

1
const { data, error } = await supabase.functions.invoke('hello', {
2
  body: { foo: 'bar' }
3
})

边缘函数 (Edge Functions) 的 CORS 头

Supabase Edge 函数的默认 CORS header。

包含 Supabase 客户端库发送的所有 header，并允许所有标准的 HTTP 方法。对于具有通配符 origin 的简单 CORS 配置，请使用此配置。

1
import { corsHeaders } from '@supabase/supabase-js/cors'
2
3
Deno.serve(async (req) => {
4
  if (req.method === 'OPTIONS') {
5
    return new Response('ok', { headers: corsHeaders })
6
  }
7
8
  return new Response(
9
    JSON.stringify({ data: 'Hello' }),
10
    { headers: { ...corsHeaders, 'Content-Type': 'application/json' } }
11
  )
12
})

更新授权令牌

setAuth(token)

更新授权 header

参数

token字符串
在授权 header 中发送的新 jwt token

返回类型

void

1
functions.setAuth(session.access_token)

订阅频道

on(type, filter, callback)

创建一个事件处理程序，用于监听更改。

默认情况下，广播和存在性对所有项目都已启用。
默认情况下，由于数据库性能和安全问题，对数据库更改的侦听在新项目中是禁用的。你可以通过管理实时的复制来启用它。
你可以通过将表的 REPLICA IDENTITY 设置为 FULL（例如，ALTER TABLE your_table REPLICA IDENTITY FULL;）来接收更新和删除的“先前”数据。
行级安全性不适用于删除语句。当启用 RLS 并且复制标识设置为 full 时，仅将主键发送给客户端。

参数

type以下选项之一
- 选项 1"presence"
- 选项 2"postgres_changes"
- 选项 3"broadcast"
- 选项 4"system"
filter以下选项之一
- Option 1object
- Option 2object
- 选项 3对象
- 选项 4RealtimePostgresChangesFilter
- 选项 5RealtimePostgresChangesFilter
- 选项 6RealtimePostgresChangesFilter
- 选项 7RealtimePostgresChangesFilter
- 选项 8RealtimePostgresChangesFilter
- 选项 9object
- 选项 10object
- 选项 11object
- 选项 12object
- 选项 13object
回调函数函数

1
const channel = supabase.channel("room1")
2
3
channel.on("broadcast", { event: "cursor-pos" }, (payload) => {
4
  console.log("Cursor position received!", payload);
5
}).subscribe((status) => {
6
  if (status === "SUBSCRIBED") {
7
    channel.send({
8
      type: "broadcast",
9
      event: "cursor-pos",
10
      payload: { x: Math.random(), y: Math.random() },
11
    });
12
  }
13
});

取消订阅频道

removeChannel(channel)

取消订阅并从实时客户端中删除实时通道。

删除频道是维护项目实时服务性能以及数据库性能的好方法（如果你正在侦听 Postgres 更改）。Supabase 会在客户端断开连接 30 秒后自动处理清理，但未使用的频道可能会导致更多客户端同时订阅而导致性能下降。

参数

channelRealtimeChannel
Realtime channel 的名称。

返回类型

Promise<以下选项之一>

选项 1"error"
选项 2"ok"
选项 3"timed out"

1
supabase.removeChannel(myChannel)

取消订阅所有频道

removeAllChannels()

取消订阅并从实时客户端删除所有实时通道。

删除频道是维护项目实时服务性能以及数据库性能的好方法（如果你正在侦听 Postgres 更改）。Supabase 会在客户端断开连接 30 秒后自动处理清理，但未使用的频道可能会导致更多客户端同时订阅而导致性能下降。

返回类型

Promise<Array<以下选项之一>>

1
supabase.removeAllChannels()

获取所有频道

getChannels()

返回所有实时通道。

返回类型

Array<RealtimeChannel>

1
const channels = supabase.getChannels()

广播消息

send(args, opts)

向 channel 发送消息。

使用 REST 时，您无需订阅 channel
REST 调用仅从 2.37.0 开始可用

参数

argsobject
发送到 channel 的参数
opts{ [key: string]: any }
在发送过程中使用的选项

返回类型

Promise<以下选项之一>

选项 1"ok"
选项 2"timed out"
选项 3"error"

1
supabase
2
  .channel('room1')
3
  .subscribe((status) => {
4
    if (status === 'SUBSCRIBED') {
5
      channel.send({
6
        type: 'broadcast',
7
        event: 'cursor-pos',
8
        payload: { x: Math.random(), y: Math.random() },
9
      })
10
    }
11
  })

设置认证令牌

setAuth(token)

设置用于 channel 订阅授权和 Realtime RLS 的 JWT 访问 token。

如果参数为 null，它将使用 accessToken 回调函数或客户端上设置的 token。

在回调函数中使用时，它会将 token 的值设置为客户端内部。

当显式提供 token 时，它将在 channel 操作（包括 removeChannel 和 resubscribe）期间保留。在不带参数的情况下调用 setAuth()，才会调用 accessToken 回调函数。

参数

token以下选项之一
用于覆盖客户端上设置的 token 的 JWT 字符串。
- 选项 1null
- 选项 2string

返回类型

Promise<void>

1
// Use a manual token (preserved across resubscribes, ignores accessToken callback)
2
client.realtime.setAuth('my-custom-jwt')
3
4
// Switch back to using the accessToken callback
5
client.realtime.setAuth()

文件存储

本节包含处理文件存储桶的方法。

访问存储 bucket

from(id)

在 bucket 中执行文件操作。

参数

idstring
要操作的 bucket id。

1
const avatars = supabase.storage.from('avatars')

列出所有存储桶

listBuckets(options?)

检索现有项目中所有存储 bucket 的详细信息。

所需的 RLS 策略权限
- buckets 表权限：select
- objects 表权限：无
请参阅存储指南，了解访问控制的工作方式

参数

options
可选
ListBucketOptions
列出 bucket 的查询参数

返回类型

Promise<以下选项之一>

Option 1object
Option 2object

1
const { data, error } = await supabase
2
  .storage
3
  .listBuckets()

检索存储桶

getBucket(id)

检索现有的存储存储桶的详细信息。

所需的 RLS 策略权限
- buckets 表权限：select
- objects 表权限：无
请参阅存储指南，了解访问控制的工作方式

参数

idstring
你要检索的存储桶的唯一标识符。

返回类型

Promise<以下选项之一>

Option 1object
Option 2object

1
const { data, error } = await supabase
2
  .storage
3
  .getBucket('avatars')

创建存储桶

createBucket(id, options)

创建一个新的存储存储桶

所需的 RLS 策略权限
- buckets 表权限：insert
- objects 表权限：无
请参阅存储指南，了解访问控制的工作方式

参数

idstring
你要创建的存储桶的唯一标识符。
optionsobject

返回类型

Promise<以下选项之一>

Option 1object
Option 2object

1
const { data, error } = await supabase
2
  .storage
3
  .createBucket('avatars', {
4
    public: false,
5
    allowedMimeTypes: ['image/png'],
6
    fileSizeLimit: 1024
7
  })

清空存储桶

emptyBucket(id)

删除单个存储桶中的所有对象。

所需的 RLS 策略权限
- buckets 表权限：select
- objects 表权限：select 和 delete
请参阅存储指南，了解访问控制的工作方式

参数

idstring
您想要清空的 bucket 的唯一标识符。

返回类型

Promise<以下选项之一>

Option 1object
Option 2object

1
const { data, error } = await supabase
2
  .storage
3
  .emptyBucket('avatars')

更新存储桶

updateBucket(id, options)

更新存储 bucket

所需的 RLS 策略权限
- buckets 表权限：select 和 update
- objects 表权限：无
请参阅存储指南，了解访问控制的工作方式

参数

idstring
您正在更新的 bucket 的唯一标识符。
optionsobject

返回类型

Promise<以下选项之一>

Option 1object
Option 2object

1
const { data, error } = await supabase
2
  .storage
3
  .updateBucket('avatars', {
4
    public: false,
5
    allowedMimeTypes: ['image/png'],
6
    fileSizeLimit: 1024
7
  })

删除存储桶

deleteBucket(id)

删除现有的存储桶。如果存储桶内存在现有对象，则无法删除存储桶。你必须首先 empty() 存储桶。

所需的 RLS 策略权限
- buckets 表权限：select 和 delete
- objects 表权限：无
请参阅存储指南，了解访问控制的工作方式

参数

idstring
您想要删除的 bucket 的唯一标识符。

返回类型

Promise<以下选项之一>

Option 1object
Option 2object

1
const { data, error } = await supabase
2
  .storage
3
  .deleteBucket('avatars')

上传文件

upload(path, fileBody, fileOptions?)

将文件上传到现有的存储桶。

所需的 RLS 策略权限
- buckets 表权限：无
- objects 表权限：仅当上传新文件时为 insert，当更新文件时为 select、insert 和 update
请参阅存储指南，了解访问控制的工作方式
对于 React Native，使用 Blob、File 或 FormData 无法按预期工作。而是使用来自 base64 文件数据的 ArrayBuffer 上传文件，请参阅下面的示例。

参数

path字符串
文件路径，包括文件名。应采用 folder/subfolder/filename.png 的格式。在尝试上传之前，bucket 必须已经存在。
fileBodyFileBody
要存储在 bucket 中的文件的 body。
fileOptions
可选
FileOptions
可选的文件上传选项，包括 cacheControl、contentType、upsert 和 metadata。

返回类型

Promise<以下选项之一>

Option 1object
Option 2object

1
const avatarFile = event.target.files[0]
2
const { data, error } = await supabase
3
  .storage
4
  .from('avatars')
5
  .upload('public/avatar1.png', avatarFile, {
6
    cacheControl: '3600',
7
    upsert: false
8
  })

替换现有文件

update(path, fileBody, fileOptions?)

用新文件替换指定路径处的现有文件。

所需的 RLS 策略权限
- buckets 表权限：无
- objects 表权限：update 和 select
请参阅存储指南，了解访问控制的工作方式
对于 React Native，使用 Blob、File 或 FormData 无法按预期工作。而是使用来自 base64 文件数据的 ArrayBuffer 更新文件，请参阅下面的示例。

参数

path字符串
相对文件路径。应采用 folder/subfolder/filename.png 的格式。在尝试更新之前，bucket 必须已经存在。
fileBody以下选项之一
要存储在 bucket 中的文件的 body。
- 选项 1string
- 选项 2ArrayBuffer
- 选项 3ReadableStream
- 选项 4Blob
- 选项 5File
- 选项 6FormData
- 选项 7@types/node.__global.NodeJS.ReadableStream
- 选项 8URLSearchParams
- 选项 9ArrayBufferView
- 选项 10@types/node.__global.Buffer
fileOptions
可选
FileOptions
可选的文件上传选项，包括 cacheControl、contentType、upsert 和 metadata。

返回类型

Promise<以下选项之一>

Option 1object
Option 2object

1
const avatarFile = event.target.files[0]
2
const { data, error } = await supabase
3
  .storage
4
  .from('avatars')
5
  .update('public/avatar1.png', avatarFile, {
6
    cacheControl: '3600',
7
    upsert: true
8
  })

移动现有文件

move(fromPath, toPath, options?)

将现有文件移动到同一 bucket 中的新路径。

所需的 RLS 策略权限
- buckets 表权限：无
- objects 表权限：update 和 select
请参阅存储指南，了解访问控制的工作方式

参数

fromPath字符串
原始文件路径，包括当前文件名。例如 folder/image.png。
toPath字符串
新文件路径，包括新文件名。例如 folder/image-new.png。
options
可选
DestinationOptions
目标选项。

返回类型

Promise<以下选项之一>

Option 1object
Option 2object

1
const { data, error } = await supabase
2
  .storage
3
  .from('avatars')
4
  .move('public/avatar1.png', 'private/avatar2.png')

复制现有文件

copy(fromPath, toPath, options?)

将现有文件复制到同一 bucket 中的新路径。

所需的 RLS 策略权限
- buckets 表权限：无
- objects 表权限：insert 和 select
请参阅存储指南，了解访问控制的工作方式

参数

fromPath字符串
原始文件路径，包括当前文件名。例如 folder/image.png。
toPath字符串
新文件路径，包括新文件名。例如 folder/image-copy.png。
options
可选
DestinationOptions
目标选项。

返回类型

Promise<以下选项之一>

Option 1object
Option 2object

1
const { data, error } = await supabase
2
  .storage
3
  .from('avatars')
4
  .copy('public/avatar1.png', 'private/avatar2.png')

创建签名 URL

createSignedUrl(path, expiresIn, options?)

创建签名 URL。使用签名 URL 可以共享文件一段时间。

所需的 RLS 策略权限
- buckets 表权限：无
- objects 表权限：select
请参阅存储指南，了解访问控制的工作方式

参数

path字符串
文件路径，包括当前文件名。例如 folder/image.png。
expiresIn数字
签名 URL 过期前的秒数。例如，60 表示 URL 有效一分钟。
options
可选
object

返回类型

Promise<以下选项之一>

Option 1object
Option 2object

1
const { data, error } = await supabase
2
  .storage
3
  .from('avatars')
4
  .createSignedUrl('folder/avatar1.png', 60)

创建签名 URL

createSignedUrls(paths, expiresIn, options?)

创建多个签名 URL。使用签名 URL 可以共享文件，并在固定时间内有效。

所需的 RLS 策略权限
- buckets 表权限：无
- objects 表权限：select
请参阅存储指南，了解访问控制的工作方式

参数

pathsArray<string>
要下载的文件路径，包括当前文件名。例如 ['folder/image.png', 'folder2/image2.png']。
expiresIn数字
签名 URL 过期前的秒数。例如，60 表示 URL 有效一分钟。
options
可选
object

返回类型

Promise<以下选项之一>

Option 1object
Option 2object

1
const { data, error } = await supabase
2
  .storage
3
  .from('avatars')
4
  .createSignedUrls(['folder/avatar1.png', 'folder/avatar2.png'], 60)

创建签名上传 URL

createSignedUploadUrl(path, options?)

创建签名上传 URL。可以使用签名上传 URL 将文件上传到存储桶，无需进一步身份验证。它们有效期为 2 小时。

所需的 RLS 策略权限
- buckets 表权限：无
- objects 表权限：insert
请参阅存储指南，了解访问控制的工作方式

参数

path字符串
文件路径，包括当前文件名。例如 folder/image.png。
options
可选
object

返回类型

Promise<以下选项之一>

Option 1object
Option 2object

1
const { data, error } = await supabase
2
  .storage
3
  .from('avatars')
4
  .createSignedUploadUrl('folder/cat.jpg')

上传到签名 URL

uploadToSignedUrl(path, token, fileBody, fileOptions?)

使用从 createSignedUploadUrl 生成的 token 上传文件。

所需的 RLS 策略权限
- buckets 表权限：无
- objects 表权限：无
请参阅存储指南，了解访问控制的工作方式

参数

path字符串
文件路径，包括文件名。应采用 folder/subfolder/filename.png 的格式。在尝试上传之前，bucket 必须已经存在。
token字符串
从 createSignedUploadUrl 生成的 token
fileBodyFileBody
要存储在 bucket 中的文件的 body。
fileOptions
可选
FileOptions
HTTP 标头 (cacheControl, contentType 等)。注意： upsert 选项在这里不起作用。要启用 upsert 行为，请在调用 createSignedUploadUrl() 时传递 { upsert: true }。

返回类型

Promise<以下选项之一>

Option 1object
Option 2object

1
const { data, error } = await supabase
2
  .storage
3
  .from('avatars')
4
  .uploadToSignedUrl('folder/cat.jpg', 'token-from-createSignedUploadUrl', file)

检索公共 URL

getPublicUrl(path, options?)

一个简单的便捷函数，用于获取公共存储桶中资源的 URL。如果您不想使用此函数，可以通过将存储桶 URL 与资源路径连接来构造公共 URL。此函数不会验证存储桶是否为公共存储桶。如果为非公共存储桶创建公共 URL，您将无法下载该资源。

存储桶需要设置为公共存储桶，可以通过 updateBucket() 或通过访问 supabase.com/dashboard 上的 Storage，点击存储桶上的溢出菜单并选择“设为公共”来实现。
所需的 RLS 策略权限
- buckets 表权限：无
- objects 表权限：无
请参阅存储指南，了解访问控制的工作方式

参数

path字符串
用于生成公共 URL 的文件路径和名称。例如 folder/image.png。
options
可选
object

返回类型

object

1
const { data } = supabase
2
  .storage
3
  .from('public-bucket')
4
  .getPublicUrl('folder/avatar1.png')

下载文件

download(path, options?, parameters?)

从私有存储桶下载文件。对于公共存储桶，请向从 getPublicUrl 返回的 URL 发送请求。

所需的 RLS 策略权限
- buckets 表权限：无
- objects 表权限：select
请参阅存储指南，了解访问控制的工作方式

参数

path字符串
要下载的文件的完整路径和文件名。例如 folder/image.png。
options
可选
选项
parameters
可选
FetchParameters
其他 fetch 参数，例如用于取消的 signal。支持标准的 fetch 选项，包括缓存控制。

1
const { data, error } = await supabase
2
  .storage
3
  .from('avatars')
4
  .download('folder/avatar1.png')

删除存储桶中的文件

remove(paths)

删除同一存储桶中的文件

所需的 RLS 策略权限
- buckets 表权限：无
- objects 表权限：delete 和 select
请参阅存储指南，了解访问控制的工作方式

参数

pathsArray<string>
要删除的文件数组，包括路径和文件名。例如 ['folder/image.png']。

返回类型

Promise<以下选项之一>

Option 1object
Option 2object

1
const { data, error } = await supabase
2
  .storage
3
  .from('avatars')
4
  .remove(['folder/avatar1.png'])

列出存储桶中的所有文件

list(path?, options?, parameters?)

列出存储桶路径内的所有文件和文件夹。

所需的 RLS 策略权限
- buckets 表权限：无
- objects 表权限：select
请参阅存储指南，了解访问控制的工作方式

参数

path
可选
字符串
文件夹路径。
options
可选
SearchOptions
搜索选项，包括 limit（默认为 100）、offset、sortBy 和 search
parameters
可选
FetchParameters
可选的 fetch 参数，包括用于取消的 signal

返回类型

Promise<以下选项之一>

Option 1object
Option 2object

1
const { data, error } = await supabase
2
  .storage
3
  .from('avatars')
4
  .list('folder', {
5
    limit: 100,
6
    offset: 0,
7
    sortBy: { column: 'name', order: 'asc' },
8
  })

检查文件是否存在

exists(path)

检查文件是否存在。

参数

path字符串
文件路径，包括文件名。例如 folder/image.png。

返回类型

Promise<以下选项之一>

Option 1object
Option 2object

1
const { data, error } = await supabase
2
  .storage
3
  .from('avatars')
4
  .exists('folder/avatar1.png')

获取文件元数据

info(path)

检索现有文件的详细信息。

参数

path字符串
文件路径，包括文件名。例如 folder/image.png。

返回类型

Promise<以下选项之一>

Option 1object
Option 2object

1
const { data, error } = await supabase
2
  .storage
3
  .from('avatars')
4
  .info('folder/avatar1.png')

列出文件 (v2)

listV2(options?, parameters?)

此方法签名将来可能会更改

参数

options
可选
SearchV2Options
搜索选项
parameters
可选
FetchParameters

返回类型

Promise<以下选项之一>

Option 1object
Option 2object

将文件转换为 base64

toBase64(data)

参数

datastring

返回类型

字符串

分析 Bucket

本节包含用于处理 Analytics Buckets 的方法。

访问 analytics bucket

创建新的 StorageAnalyticsClient 实例

Public alpha：此 API 是公共 alpha 版本的一部分，可能不可用于您的帐户类型。

参数

urlstring
存储 API 的基本 URL
headers{ [key: string]: string }
包含在请求中的 HTTP 标头
fetch
可选
function
可选的自定义 fetch 实现

1
const client = new StorageAnalyticsClient(url, headers)

创建 analytics bucket

createBucket(name)

使用 Iceberg 表 Analytics buckets 创建新的 analytics bucket。Analytics buckets 针对分析查询和数据处理进行了优化

Public alpha：此 API 是公共 alpha 版本的一部分，可能不可用于您的帐户类型。

使用 Iceberg 表创建新的 analytics bucket
Analytics buckets 针对分析查询和数据处理进行了优化

参数

namestring
您正在创建的存储桶的唯一名称

返回类型

Promise<以下选项之一>

Option 1object
Option 2object

1
const { data, error } = await supabase
2
  .storage
3
  .analytics
4
  .createBucket('analytics-data')

列出 analytics buckets

listBuckets(options?)

检索现有项目中所有 Analytics Storage buckets 的详细信息。仅返回类型为 'ANALYTICS' 的 buckets

Public alpha：此 API 是公共 alpha 版本的一部分，可能不可用于您的帐户类型。

检索现有项目中所有 Analytics Storage buckets 的详细信息
仅返回类型为 'ANALYTICS' 的 buckets

参数

options
可选
object
列出 bucket 的查询参数

返回类型

Promise<以下选项之一>

Option 1object
Option 2object

1
const { data, error } = await supabase
2
  .storage
3
  .analytics
4
  .listBuckets({
5
    limit: 10,
6
    offset: 0,
7
    sortColumn: 'created_at',
8
    sortOrder: 'desc'
9
  })

删除 analytics bucket

deleteBucket(bucketName)

删除现有的 analytics bucket。包含现有对象的 bucket 无法删除。您必须先清空 bucket 才能删除。

Public alpha：此 API 是公共 alpha 版本的一部分，可能不可用于您的帐户类型。

删除 analytics bucket

参数

bucketNamestring
您想要删除的 bucket 的唯一标识符

返回类型

Promise<以下选项之一>

Option 1object
Option 2object

1
const { data, error } = await supabase
2
  .storage
3
  .analytics
4
  .deleteBucket('analytics-data')

向量 Bucket

本节包含用于处理 Vector Buckets 的方法。

访问 vector bucket

from(vectorBucketName)

访问特定 vector bucket 的操作。返回 bucket 内索引和向量操作的限定客户端

Public alpha：此 API 是公共 alpha 版本的一部分，可能不可用于您的帐户类型。

参数

vectorBucketNamestring
vector bucket 的名称

1
const bucket = supabase.storage.vectors.from('embeddings-prod')

创建 vector bucket

createBucket(vectorBucketName)

创建新的 vector bucket。Vector buckets 是向量索引及其数据的容器

Public alpha：此 API 是公共 alpha 版本的一部分，可能不可用于您的帐户类型。

参数

vectorBucketNamestring
vector bucket 的唯一名称

返回类型

Promise<以下选项之一>

Option 1SuccessResponse
Option 2ErrorResponse

1
const { data, error } = await supabase
2
  .storage
3
  .vectors
4
  .createBucket('embeddings-prod')

删除 vector bucket

deleteBucket(vectorBucketName)

删除 vector bucket（bucket 必须为空）。必须先删除所有索引才能删除 bucket

Public alpha：此 API 是公共 alpha 版本的一部分，可能不可用于您的帐户类型。

参数

vectorBucketNamestring
要删除的 vector bucket 的名称

返回类型

Promise<以下选项之一>

Option 1SuccessResponse
Option 2ErrorResponse

1
const { data, error } = await supabase
2
  .storage
3
  .vectors
4
  .deleteBucket('embeddings-old')

检索 vector bucket

getBucket(vectorBucketName)

检索特定 vector bucket 的元数据

Public alpha：此 API 是公共 alpha 版本的一部分，可能不可用于您的帐户类型。

参数

vectorBucketNamestring
vector bucket 的名称

返回类型

Promise<以下选项之一>

Option 1SuccessResponse
Option 2ErrorResponse

1
const { data, error } = await supabase
2
  .storage
3
  .vectors
4
  .getBucket('embeddings-prod')
5
6
console.log('Bucket created:', data?.vectorBucket.creationTime)

列出所有 vector buckets

listBuckets(options)

列出 vector buckets，并提供可选的筛选和分页

Public alpha：此 API 是公共 alpha 版本的一部分，可能不可用于您的帐户类型。

参数

optionsListVectorBucketsOptions
可选的筛选器（prefix、maxResults、nextToken）

返回类型

Promise<以下选项之一>

Option 1SuccessResponse
Option 2ErrorResponse

1
const { data, error } = await supabase
2
  .storage
3
  .vectors
4
  .listBuckets({ prefix: 'embeddings-' })
5
6
data?.vectorBuckets.forEach(bucket => {
7
  console.log(bucket.vectorBucketName)
8
})

创建 vector 索引

createIndex(options)

在此 bucket 中创建新的 vector 索引。便捷方法，自动包含 bucket 名称

Public alpha：此 API 是公共 alpha 版本的一部分，可能不可用于您的帐户类型。

参数

optionsOmit
索引配置（vectorBucketName 自动设置）

返回类型

Promise<以下选项之一>

Option 1SuccessResponse
Option 2ErrorResponse

1
const bucket = supabase.storage.vectors.from('embeddings-prod')
2
await bucket.createIndex({
3
  indexName: 'documents-openai',
4
  dataType: 'float32',
5
  dimension: 1536,
6
  distanceMetric: 'cosine',
7
  metadataConfiguration: {
8
    nonFilterableMetadataKeys: ['raw_text']
9
  }
10
})

删除 vector 索引

deleteIndex(indexName)

从此 bucket 中删除索引。便捷方法，自动包含 bucket 名称

Public alpha：此 API 是公共 alpha 版本的一部分，可能不可用于您的帐户类型。

参数

indexNamestring
要删除的索引的名称

返回类型

Promise<以下选项之一>

Option 1SuccessResponse
Option 2ErrorResponse

1
const bucket = supabase.storage.vectors.from('embeddings-prod')
2
await bucket.deleteIndex('old-index')

检索 vector 索引

getIndex(indexName)

检索此 bucket 中特定索引的元数据。便捷方法，自动包含 bucket 名称

Public alpha：此 API 是公共 alpha 版本的一部分，可能不可用于您的帐户类型。

参数

indexNamestring
要检索的索引的名称

返回类型

Promise<以下选项之一>

Option 1SuccessResponse
Option 2ErrorResponse

1
const bucket = supabase.storage.vectors.from('embeddings-prod')
2
const { data } = await bucket.getIndex('documents-openai')
3
console.log('Dimension:', data?.index.dimension)

列出所有 vector 索引

listIndexes(options)

列出此 bucket 中的索引。便捷方法，自动包含 bucket 名称

Public alpha：此 API 是公共 alpha 版本的一部分，可能不可用于您的帐户类型。

参数

optionsOmit
列出选项（vectorBucketName 自动设置）

返回类型

Promise<以下选项之一>

Option 1SuccessResponse
Option 2ErrorResponse

1
const bucket = supabase.storage.vectors.from('embeddings-prod')
2
const { data } = await bucket.listIndexes({ prefix: 'documents-' })

访问 vector 索引

VectorBucketScope(indexName)

访问此 bucket 中特定索引的操作。返回用于向量数据操作的限定客户端

Public alpha：此 API 是公共 alpha 版本的一部分，可能不可用于您的帐户类型。

参数

indexNamestring
索引的名称

1
const index = supabase.storage.vectors.from('embeddings-prod').index('documents-openai')
2
3
// Insert vectors
4
await index.putVectors({
5
  vectors: [
6
    { key: 'doc-1', data: { float32: [...] }, metadata: { title: 'Intro' } }
7
  ]
8
})
9
10
// Query similar vectors
11
const { data } = await index.queryVectors({
12
  queryVector: { float32: [...] },
13
  topK: 5
14
})

从索引中删除向量

deleteVectors(options)

从此索引中按键删除向量。便捷方法，自动包含 bucket 和索引名称

Public alpha：此 API 是公共 alpha 版本的一部分，可能不可用于您的帐户类型。

参数

optionsOmit
删除选项（bucket 和索引名称自动设置）

返回类型

Promise<以下选项之一>

Option 1SuccessResponse
Option 2ErrorResponse

1
const index = supabase.storage.vectors.from('embeddings-prod').index('documents-openai')
2
await index.deleteVectors({
3
  keys: ['doc-1', 'doc-2', 'doc-3']
4
})

从索引中检索向量

getVectors(options)

从此索引中按键检索向量。便捷方法，自动包含 bucket 和索引名称

Public alpha：此 API 是公共 alpha 版本的一部分，可能不可用于您的帐户类型。

参数

optionsOmit
向量检索选项（bucket 和索引名称自动设置）

返回类型

Promise<以下选项之一>

Option 1SuccessResponse
Option 2ErrorResponse

1
const index = supabase.storage.vectors.from('embeddings-prod').index('documents-openai')
2
const { data } = await index.getVectors({
3
  keys: ['doc-1', 'doc-2'],
4
  returnMetadata: true
5
})

列出索引中的向量

listVectors(options)

列出此索引中的向量，并进行分页。便捷方法，自动包含 bucket 和索引名称

Public alpha：此 API 是公共 alpha 版本的一部分，可能不可用于您的帐户类型。

参数

optionsOmit
列出选项（bucket 和索引名称自动设置）

返回类型

Promise<以下选项之一>

Option 1SuccessResponse
Option 2ErrorResponse

1
const index = supabase.storage.vectors.from('embeddings-prod').index('documents-openai')
2
const { data } = await index.listVectors({
3
  maxResults: 500,
4
  returnMetadata: true
5
})

将向量添加到索引

putVectors(options)

将向量插入或更新到此索引。便捷方法，自动包含 bucket 和索引名称

Public alpha：此 API 是公共 alpha 版本的一部分，可能不可用于您的帐户类型。

参数

optionsOmit
向量插入选项（bucket 和索引名称自动设置）

返回类型

Promise<以下选项之一>

Option 1SuccessResponse
Option 2ErrorResponse

1
const index = supabase.storage.vectors.from('embeddings-prod').index('documents-openai')
2
await index.putVectors({
3
  vectors: [
4
    {
5
      key: 'doc-1',
6
      data: { float32: [0.1, 0.2, ...] },
7
      metadata: { title: 'Introduction', page: 1 }
8
    }
9
  ]
10
})

在索引中搜索向量

queryVectors(options)

在此索引中查询相似的向量。便捷方法，自动包含 bucket 和索引名称

Public alpha：此 API 是公共 alpha 版本的一部分，可能不可用于您的帐户类型。

参数

optionsOmit
查询选项（bucket 和索引名称自动设置）

返回类型

Promise<以下选项之一>

Option 1SuccessResponse
Option 2ErrorResponse

1
const index = supabase.storage.vectors.from('embeddings-prod').index('documents-openai')
2
const { data } = await index.queryVectors({
3
  queryVector: { float32: [0.1, 0.2, ...] },
4
  topK: 5,
5
  filter: { category: 'technical' },
6
  returnDistance: true,
7
  returnMetadata: true
8
})