跳到主要内容

安装配置

本章节介绍如何创建 Supabase 项目、配置开发环境，以及安装各种客户端 SDK。

创建 Supabase 项目​

注册账号​

访问 supabase.com，你可以选择以下方式注册：

  • 使用 GitHub 账号直接登录（推荐）
  • 使用邮箱注册

Supabase 免费套餐提供：

  • 500MB 数据库存储
  • 1GB 文件存储
  • 2GB 出站流量/月
  • 50,000 月活用户
  • 500MB Edge Functions 执行时间

创建新项目​

登录后，点击 "New Project" 创建项目：

  1. 选择组织：如果是首次使用，会自动创建一个个人组织
  2. 填写项目信息：
    • Name：项目名称，如 "my-first-app"
    • Database Password：数据库密码，请妥善保存
    • Region：选择离你最近的区域，如 "Northeast Asia (Tokyo)"
  3. 点击创建：等待 2-3 分钟，系统会自动初始化项目

项目初始化完成后，你会看到项目仪表板，包含数据库、认证、存储等功能的入口。

获取 API 密钥​

在项目设置中可以找到 API 密钥：

  1. 点击左侧菜单 "Settings" → "API"
  2. 记录以下信息：
    • Project URL：项目的 API 地址
    • anon public：匿名公钥，可以在客户端使用
    • service_role：服务密钥，拥有完全权限，只能在服务端使用
Project URL: https://abcdefghijklmnop.supabase.co
anon key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
service_role key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

安全提示：

  • anon 密钥可以公开，但受 RLS 策略保护
  • service_role 密钥拥有完全权限，绝对不能暴露在客户端代码中

安装客户端 SDK​

Supabase 提供了多种语言的客户端 SDK，你可以根据项目需求选择。

JavaScript / TypeScript​

最常用的 SDK，支持浏览器和 Node.js 环境：

npm install @supabase/supabase-js

基本使用：

import { createClient } from '@supabase/supabase-js'

const supabaseUrl = 'https://your-project.supabase.co'
const supabaseKey = 'your-anon-key'

const supabase = createClient(supabaseUrl, supabaseKey)

// 测试连接
async function testConnection() {
  const { data, error } = await supabase.from('todos').select('*')
  if (error) {
    console.error('连接失败:', error)
  } else {
    console.log('连接成功:', data)
  }
}

React​

针对 React 的封装，提供钩子和组件：

npm install @supabase/supabase-js @supabase/auth-helpers-react

创建 Supabase 上下文：

// lib/supabase.js
import { createClient } from '@supabase/supabase-js'

export const supabase = createClient(
  process.env.NEXT_PUBLIC_SUPABASE_URL,
  process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY
)

在组件中使用：

// components/TodoList.jsx
import { useState, useEffect } from 'react'
import { supabase } from '../lib/supabase'

function TodoList() {
  const [todos, setTodos] = useState([])

  useEffect(() => {
    fetchTodos()
  }, [])

  async function fetchTodos() {
    const { data } = await supabase.from('todos').select('*')
    setTodos(data || [])
  }

  return (
    <ul>
      {todos.map(todo => (
        <li key={todo.id}>{todo.task}</li>
      ))}
    </ul>
  )
}

Next.js​

Next.js 集成需要考虑服务端和客户端的不同环境：

npm install @supabase/supabase-js @supabase/ssr

创建客户端实例：

// utils/supabase/client.ts
import { createBrowserClient } from '@supabase/ssr'

export function createClient() {
  return createBrowserClient(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
  )
}

创建服务端实例：

// utils/supabase/server.ts
import { createServerClient } from '@supabase/ssr'
import { cookies } from 'next/headers'

export async function createClient() {
  const cookieStore = await cookies()
  
  return createServerClient(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
    {
      cookies: {
        getAll() {
          return cookieStore.getAll()
        },
        setAll(cookiesToSet) {
          try {
            cookiesToSet.forEach(({ name, value, options }) =>
              cookieStore.set(name, value, options)
            )
          } catch {
            // Server Component 中调用 setAll 会失败
            // 这是预期行为，可以忽略
          }
        },
      },
    }
  )
}

Vue.js​

Vue 3 组合式 API 集成：

npm install @supabase/supabase-js

创建 Supabase 插件：

// plugins/supabase.ts
import { createClient } from '@supabase/supabase-js'
import type { SupabaseClient } from '@supabase/supabase-js'

const supabaseUrl = import.meta.env.VITE_SUPABASE_URL
const supabaseKey = import.meta.env.VITE_SUPABASE_ANON_KEY

export const supabase: SupabaseClient = createClient(supabaseUrl, supabaseKey)

在组件中使用：

<script setup lang="ts">
import { ref, onMounted } from 'vue'
import { supabase } from '../plugins/supabase'

const todos = ref([])

onMounted(async () => {
  const { data } = await supabase.from('todos').select('*')
  todos.value = data || []
})
</script>

<template>
  <ul>
    <li v-for="todo in todos" :key="todo.id">
      {{ todo.task }}
    </li>
  </ul>
</template>

Flutter​

移动应用开发：

dependencies:
  supabase_flutter: ^2.0.0

初始化：

import 'package:supabase_flutter/supabase_flutter.dart';

Future<void> main() async {
  await Supabase.initialize(
    url: 'https://your-project.supabase.co',
    anonKey: 'your-anon-key',
  );
  runApp(MyApp());
}

final supabase = Supabase.instance.client;

使用：

// 查询数据
final response = await supabase
    .from('todos')
    .select();

// 插入数据
await supabase.from('todos').insert({
  'task': '学习 Supabase',
  'is_complete': false,
});

Python​

服务端 Python 应用：

pip install supabase

使用：

from supabase import create_client, Client

url: str = "https://your-project.supabase.co"
key: str = "your-anon-key"
supabase: Client = create_client(url, key)

# 查询数据
response = supabase.table('todos').select("*").execute()
print(response.data)

# 插入数据
data = supabase.table('todos').insert({
    "task": "学习 Supabase",
    "is_complete": False
}).execute()

Go​

Go 语言客户端：

go get github.com/nedpals/supabase-go

使用：

package main

import (
    "fmt"
    "github.com/nedpals/supabase-go"
)

func main() {
    supabaseUrl := "https://your-project.supabase.co"
    supabaseKey := "your-anon-key"
    
    client := supabase.CreateClient(supabaseUrl, supabaseKey)
    
    // 查询数据
    var result map[string]interface{}
    err := client.DB.From("todos").Select("*").Execute(&result)
    if err != nil {
        panic(err)
    }
    fmt.Println(result)
}

安装 Supabase CLI​

Supabase CLI 是一个强大的命令行工具，可以帮助你在本地开发和管理项目。

安装方式​

macOS：

brew install supabase/tap/supabase

Windows：

scoop bucket add supabase https://github.com/supabase/scoop-bucket.git
scoop install supabase

Linux：

curl -fsSL https://cli.supabase.com/install.sh | sh

npm（跨平台）：

npm install -g supabase

登录认证​

安装后需要登录 Supabase 账号：

supabase login

这会打开浏览器进行 OAuth 认证，完成后 CLI 会保存你的登录状态。

初始化本地项目​

在项目目录中初始化 Supabase：

mkdir my-supabase-app
cd my-supabase-app
supabase init

这会创建以下目录结构：

my-supabase-app/
├── supabase/
│   ├── config.toml      # 项目配置
│   ├── migrations/      # 数据库迁移文件
│   ├── seed.sql         # 种子数据
│   └── functions/       # Edge Functions
└── .gitignore

启动本地开发环境​

启动本地 Supabase 服务：

supabase start

首次启动会下载 Docker 镜像，可能需要几分钟。启动成功后会显示本地服务地址：

Started supabase local development setup.

         API URL: http://localhost:54321
          DB URL: postgresql://postgres:postgres@localhost:54322/postgres
      Studio URL: http://localhost:54323
    Inbucket URL: http://localhost:54324
      JWT secret: super-secret-jwt-token-with-at-least-32-characters-long
        anon key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
service_role key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

连接到远程项目​

将本地项目关联到远程 Supabase 项目：

supabase link --project-ref your-project-ref

项目 ID 可以在项目设置的 General 页面找到。

环境变量配置​

在实际项目中，应该使用环境变量存储敏感信息。

Next.js / React​

创建 .env.local 文件：

NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key

# 服务端使用，不要暴露给客户端
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key

Vue.js / Vite​

创建 .env 文件：

VITE_SUPABASE_URL=https://your-project.supabase.co
VITE_SUPABASE_ANON_KEY=your-anon-key

Node.js​

使用 dotenv 包：

npm install dotenv

创建 .env 文件：

SUPABASE_URL=https://your-project.supabase.co
SUPABASE_ANON_KEY=your-anon-key
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key

在代码中加载：

require('dotenv').config()

const supabase = createClient(
  process.env.SUPABASE_URL,
  process.env.SUPABASE_ANON_KEY
)

数据库迁移​

使用 CLI 管理数据库迁移：

创建迁移​

supabase migration new create_todos_table

这会在 supabase/migrations/ 目录创建一个新的迁移文件。

编写迁移 SQL​

编辑迁移文件：

-- supabase/migrations/20240101000000_create_todos_table.sql

create table todos (
  id bigint primary key generated always as identity,
  task text not null,
  is_complete boolean default false,
  created_at timestamptz default now(),
  user_id uuid references auth.users(id)
);

-- 启用 RLS
alter table todos enable row level security;

-- 创建策略
create policy "Users can view own todos"
  on todos for select
  using (auth.uid() = user_id);

应用迁移​

在本地应用迁移：

supabase db reset

推送到远程项目：

supabase db push

常见问题​

连接超时​

如果遇到连接超时，可能是网络问题：

  1. 检查网络连接
  2. 确认项目区域选择正确
  3. 检查防火墙设置

API 密钥无效​

确认使用的是正确的密钥：

  • 客户端使用 anon 密钥
  • 服务端使用 service_role 密钥
  • 密钥没有多余的空格或换行

本地开发环境启动失败​

确保 Docker 已安装并运行：

docker --version
docker ps

如果 Docker 正常但启动失败，尝试重置：

supabase stop
supabase start

下一步​

完成环境配置后，你可以继续学习：