集成 Supabase

介绍在 Apps in Toss（迷你应用）WebView 环境中集成 Supabase 的方法。Supabase JS 客户端可独立于框架运行。代码示例基于 Vite(React + TypeScript) 编写而成。

---

概要

Supabase 是提供认证、数据库（PostgreSQL）、文件存储、实时订阅等功能的开源后端服务。在 Apps in Toss WebView 环境中也可以同样使用，但 安全设置与环境变量管理很重要。

---

1. 准备

• Supabase 账户（supabase.com)
• 使用 Vite(React + TypeScript) 创建的项目
• Node.js、npm（或 yarn、pnpm）

2. 创建 Supabase 项目

1. 在 Supabase 仪表板中 New project即可创建新项目。
2. 设置项目名称、数据库密码和区域后完成创建。
3. 项目准备就绪后，可在仪表板中查看以下信息。

Project URL     : https://<project-id>.supabase.co
Publishable key : sb_publishable_xxxxxxxxxxxx

3. 设置环境变量

建议将 Supabase 连接信息作为环境变量管理以确保安全。在项目根目录中 .env 创建文件并按如下方式填写。

VITE_SUPABASE_URL=https://<project-id>.supabase.co
VITE_SUPABASE_PUBLISHABLE_KEY=sb_publishable_xxxxxxxxxxxx

4. 安装并初始化 Supabase

src/supabase/client.ts 创建文件并按如下方式初始化 Supabase 客户端。

npm install @supabase/supabase-js

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

const supabaseUrl = import.meta.env.VITE_SUPABASE_URL;
const supabasePublishableKey = import.meta.env.VITE_SUPABASE_PUBLISHABLE_KEY;

export const supabase = createClient(supabaseUrl, supabasePublishableKey);

参考

Publishable key 就像 Stripe 的 pk_live_...，Firebase 的 apiKey这类可以暴露给客户端的公开密钥。不过， 必须设置 RLS（Row Level Security）策略 。没有 RLS 时，只要有 publishable key，任何人都可以读取和写入整张表。

secret 密钥是可完全绕过 RLS 的秘密密钥。仅在服务器端使用，绝不要暴露给客户端。

5. 数据库使用示例

如果已初始化 Supabase 客户端，就可以在 React 组件中读取或写入数据。下面是 App.tsx中读取并保存单行数据的最简单示例。

在 Supabase 仪表板的 Table Editor中 users 创建表， id（int8，primary key）和 name（text）列。

import { useState, useEffect } from 'react';
import { supabase } from './supabase/client';

function App() {
  const [name, setName] = useState('');
  const [savedName, setSavedName] = useState('');

  // 从 Supabase 读取数据
  useEffect(() => {
    const fetchData = async () => {
      const { data } = await supabase.from('users').select('name').eq('id', 1).single();
      if (data) {
        setSavedName(data.name);
      }
    };
    fetchData();
  }, []);

  // 向 Supabase 写入数据
  const handleSave = async () => {
    await supabase.from('users').upsert({ id: 1, name });
    setSavedName(name);
    setName('');
  };

  return (
    <div style={{ padding: 24 }}>
      <h1>Supabase 简单示例</h1>
      <input value={name} onChange={(e) => setName(e.target.value)} placeholder="输入姓名" />
      <button onClick={handleSave}>保存</button>
      <p>已保存的姓名: {savedName || '(无)'}</p>

  );
}

export default App;

工作方式

• 读取数据（.select())

  • users 在表中 id只会获取 id 为 1 的行一次。
  • 如果存在该行 name 将值显示在屏幕上。
• 写入数据（.upsert())

  • 将输入的姓名 users 保存到表中。
  • 如果没有该行则新建，有则覆盖。

Supabase 其他功能

• 实时订阅： .channel(), .on()使用它们时，数据变更后 UI 会自动刷新。
• 文件存储： supabase.storage可以上传图片或文件。
• 认证集成： supabase.auth配合使用后可以按用户保存数据。

6. 安全检查清单

• 通过环境变量管理敏感信息

  • Supabase URL、publishable key 等不要直接写入代码， .env请用环境变量管理。
• 不要将环境文件上传到 Git 等平台

  • .env 文件 .gitignore中一定要添加。
  • 如果密钥泄露，请立即在 Supabase 仪表板重新签发密钥。
• 必须设置 Row Level Security(RLS)

  • Supabase 的所有表默认都未启用 RLS。
  • 在关闭 RLS 的情况下，只要有 publishable key，任何人都能访问整张表。
  • 部署前务必启用 RLS，并设置策略（Policy）以仅允许已认证用户访问。
  • Supabase 仪表板 Table Editor → 选择表 → RLS 可在选项卡中进行设置。
• 检查来源（Origin）限制

  • 在 Supabase 仪表板的 Authentication → URL Configuration中限制允许的域名。
  • 只允许迷你应用（WebView）域名可预防未授权访问。

允许的域名

因 SDK 版本而异。\n\nSDK 3.x https://<appName>.web.tossmini.com — 实际服务环境 https://<appName>.private-web.tossmini.com — 控制台 QR 测试环境\n\nSDK 1.x ~ 2.x https://<appName>.apps.tossmini.com — 实际服务环境 https://<appName>.private-apps.tossmini.com — 控制台 QR 测试环境