Supabase 快速入门：集成 Next.js、Astro 与 React

本文目标：在 30-60 分钟内，通过最小可运行示例，帮助你快速掌握 Supabase 与三种主流前端框架（Next.js, Astro, React）的集成方法，覆盖基础的数据库读写操作。

核心优势

零配置启动: 提供完整的代码片段与命令行指令，实现真正的“开箱即用”。

框架全覆盖: 一篇文章同时满足 Next.js, Astro, React 开发者的入门需求。

生产级实践: 虽然是快速入门，但代码结构与提示均考虑了后续扩展性。

1. 准备工作#

在开始之前，请确保你已准备好以下环境与账号：

Node.js: 版本 18 或更高。
包管理器: pnpm, npm, 或 yarn。
Supabase 账号: 注册一个免费账号即可满足本教程所有需求。

2. Supabase 项目设置#

创建项目#

登录 Supabase Dashboard。
点击 “New project” 创建一个新项目。
在项目创建后，导航到 Settings -> API 页面。
记录下你的 Project URL 和 anon (public) API key，后续步骤将频繁使用。

准备数据库表与 RLS 策略#

为了演示数据读写，我们需要一张 messages 表，并为其配置行级安全 (Row Level Security, RLS) 策略。

安全提示
以下 SQL 策略仅为演示目的，允许任何匿名用户读写 messages 表。在生产环境中，你必须根据业务需求编写更严格的安全策略。

在 Supabase SQL Editor 中执行以下脚本：

1
-- 1) 创建用于演示的 "messages" 表
2
create table if not exists public.messages (
3
  id bigserial primary key,
4
  content text not null,
5
  created_at timestamp with time zone default now()
6
);
7

8
-- 2) 为 "messages" 表启用行级安全 (RLS)
9
alter table public.messages enable row level security;
10

11
-- 3) 创建宽松的演示策略（生产环境请勿直接使用！）
12
create policy "Allow anonymous read" on public.messages for select using (true);
13
create policy "Allow anonymous insert" on public.messages for insert with check (true);

配置环境变量#

在你的本地前端项目根目录下，为不同框架创建对应的 .env.local 或 .env 文件，并填入之前记录的 Supabase 项目信息。

命名约定

不同前端框架对环境变量有不同的命名要求，请务必遵循：

Next.js: NEXT_PUBLIC_
Astro: PUBLIC_
React (Vite): VITE_

Next.js (.env.local):

1
NEXT_PUBLIC_SUPABASE_URL=你的项目URL
2
NEXT_PUBLIC_SUPABASE_ANON_KEY=你的anonKey

Astro (.env 或 .env.local):

1
PUBLIC_SUPABASE_URL=你的项目URL
2
PUBLIC_SUPABASE_ANON_KEY=你的anonKey

React (Vite) (.env.local):

1
VITE_SUPABASE_URL=你的项目URL
2
VITE_SUPABASE_ANON_KEY=你的anonKey

3. 前端框架集成示例#

现在，我们将分别演示如何在 Next.js, Astro, 和 React (Vite) 中集成 Supabase。

Next.js 最小可运行示例#

1) 初始化项目与依赖#

1
pnpm dlx create-next-app@latest supa-next --ts --app --use-pnpm
2
cd supa-next
3
pnpm add @supabase/supabase-js

2) 创建 Supabase 客户端#

新建 src/lib/supabaseClient.ts 文件：

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

3
export const supabase = createClient(
4
  process.env.NEXT_PUBLIC_SUPABASE_URL!,
5
  process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
6
)

3) 在页面中读写数据#

修改 app/page.tsx 文件，实现消息的加载与新增：

1
'use client'
2

3
import { useEffect, useState, useCallback } from 'react'
4
import { supabase } from '@/lib/supabaseClient'
5

6
type Message = {
7
  id: number;
8
  content: string;
9
};
10

11
export default function Page() {
12
  const [text, setText] = useState('')
13
  const [rows, setRows] = useState<Message[]>([])
14
  const [loading, setLoading] = useState(false)
15
  const [error, setError] = useState<string | null>(null)
16

17
  const loadMessages = useCallback(async () => {
18
    setLoading(true)
19
    setError(null)
20
    try {
21
      const { data, error: dbError } = await supabase
22
        .from('messages')
23
        .select('id, content')
24
        .order('id', { ascending: false })
25
        .limit(20)
26

27
      if (dbError) throw dbError
28
      setRows(data || [])
29
    } catch (err: any) {
30
      setError(err.message)
31
    } finally {
32
      setLoading(false)
33
    }
34
  }, [])
35

36
  const insertMessage = async () => {
37
    if (!text.trim()) return
38
    setLoading(true)
39
    setError(null)
40
    try {
41
      const { error: dbError } = await supabase.from('messages').insert({ content: text.trim() })
42
      if (dbError) throw dbError
43
      setText('')
44
      await loadMessages()
45
    } catch (err: any) {
46
      setError(err.message)
47
    } finally {
48
      setLoading(false)
49
    }
50
  }
51

52
  useEffect(() => {
53
    void loadMessages()
54
  }, [loadMessages])
55

56
  return (
57
    <main style={{ padding: 24, maxWidth: '600px', margin: 'auto' }}>
58
      <h1>Supabase × Next.js</h1>
59
      <div style={{ display: 'flex', gap: 8, marginBottom: 16 }}>
60
        <input
61
          value={text}
62
          onChange={(e) => setText(e.target.value)}
63
          placeholder="输入消息"
64
          style={{ flex: 1 }}
65
        />
66
        <button onClick={insertMessage} disabled={loading}>
67
          {loading ? '提交中…' : '新增'}
68
        </button>
69
      </div>
70
      {error && <p style={{ color: 'red' }}>Error: {error}</p>}
71
      {loading && <p>Loading messages...</p>}
72
      <ul>
73
        {rows.map((r) => (
74
          <li key={r.id}>#{r.id}: {r.content}</li>
75
        ))}
76
      </ul>
77
    </main>
78
  )
79
}

4) 运行#

1
pnpm dev

Astro 最小可运行示例#

Astro 示例将利用其组件化的特性，将客户端逻辑封装起来，使页面更整洁。

1) 初始化项目#

1
pnpm create astro@latest supa-astro -- --template minimal
2
cd supa-astro
3
pnpm add @supabase/supabase-js

2) 创建 Supabase 客户端组件#

新建 src/components/SupaMessages.astro 文件。这个组件将处理所有与 Supabase 的交互。

1
---
2
---
3
<div id="messages-container">
4
  <h1>Supabase × Astro</h1>
5
  <div style={{ display: 'flex', gap: 8, marginBottom: 16 }}>
6
    <input id="msg-input" placeholder="输入消息" style={{ flex: 1 }} />
7
    <button id="add-btn">新增</button>
8
  </div>
9
  <div id="error-display" style={{ color: 'red' }}></div>
10
  <p id="loading-display">Loading messages...</p>
11
  <ul id="messages-list"></ul>
12
</div>
13

14
<script>
15
  import { createClient } from "@supabase/supabase-js";
16

17
  const supabase = createClient(
18
    import.meta.env.PUBLIC_SUPABASE_URL,
19
    import.meta.env.PUBLIC_SUPABASE_ANON_KEY
20
  );
21

22
  const container = document.getElementById('messages-container');
23
  const listEl = container.querySelector('#messages-list');
24
  const inputEl = container.querySelector('#msg-input') as HTMLInputElement;
25
  const addBtn = container.querySelector('#add-btn');
26
  const errorDisplay = container.querySelector('#error-display');
27
  const loadingDisplay = container.querySelector('#loading-display');
28

29
  const loadMessages = async () => {
30
    loadingDisplay.style.display = 'block';
31
    errorDisplay.textContent = '';
32
    try {
33
      const { data, error } = await supabase
34
        .from('messages')
35
        .select('id, content')
36
        .order('id', { ascending: false })
37
        .limit(20);
38

39
      if (error) throw error;
40

41
      listEl.innerHTML = (data || [])
42
        .map((r) => `<li>#${r.id}: ${r.content}</li>`)
43
        .join('');
44
    } catch (err: any) {
45
      errorDisplay.textContent = `Error: ${err.message}`;
46
    } finally {
47
      loadingDisplay.style.display = 'none';
48
    }
49
  };
50

51
  addBtn.addEventListener('click', async () => {
52
    const content = inputEl.value.trim();
53
    if (!content) return;
54

55
    addBtn.setAttribute('disabled', 'true');
56
    errorDisplay.textContent = '';
57

58
    try {
59
      const { error } = await supabase.from('messages').insert({ content });
60
      if (error) throw error;
61
      inputEl.value = '';
62
      await loadMessages();
63
    } catch (err: any) {
64
      errorDisplay.textContent = `Error: ${err.message}`;
65
    } finally {
66
      addBtn.removeAttribute('disabled');
67
    }
68
  });
69

70
  // Initial load
71
  loadMessages();
72
</script>

3) 在页面中使用组件#

修改 src/pages/index.astro：

1
---
2
import SupaMessages from '../components/SupaMessages.astro';
3
---
4

5
<html lang="zh-CN">
6
  <head>
7
    <meta charset="utf-8" />
8
    <meta name="viewport" content="width=device-width, initial-scale=1" />
9
    <title>Supabase × Astro</title>
10
    <style>
11
      body {
12
        padding: 24px;
13
        max-width: 600px;
14
        margin: auto;
15
      }
16
    </style>
17
  </head>
18
  <body>
19
    <SupaMessages />
20
  </body>
21
</html>

4) 运行#

1
pnpm dev

React（Vite）最小可运行示例#

1) 初始化项目与依赖#

1
pnpm create vite@latest supa-react -- --template react-ts
2
cd supa-react
3
pnpm add @supabase/supabase-js

2) 创建 Supabase 客户端#

新建 src/lib/supabase.ts：

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

3
export const supabase = createClient(
4
  import.meta.env.VITE_SUPABASE_URL!,
5
  import.meta.env.VITE_SUPABASE_ANON_KEY!
6
)

3) 在 `App.tsx` 中读写数据#

修改 src/App.tsx：

1
import { useEffect, useState, useCallback } from 'react'
2
import { supabase } from './lib/supabase'
3

4
type Message = {
5
  id: number;
6
  content: string;
7
};
8

9
function App() {
10
  const [text, setText] = useState('')
11
  const [rows, setRows] = useState<Message[]>([])
12
  const [loading, setLoading] = useState(false)
13
  const [error, setError] = useState<string | null>(null)
14

15
  const loadMessages = useCallback(async () => {
16
    setLoading(true)
17
    setError(null)
18
    try {
19
      const { data, error: dbError } = await supabase
20
        .from('messages')
21
        .select('id, content')
22
        .order('id', { ascending: false })
23
        .limit(20)
24

25
      if (dbError) throw dbError
26
      setRows(data || [])
27
    } catch (err: any) {
28
      setError(err.message)
29
    } finally {
30
      setLoading(false)
31
    }
32
  }, [])
33

34
  const insertMessage = async () => {
35
    if (!text.trim()) return
36
    setLoading(true)
37
    setError(null)
38
    try {
39
      const { error: dbError } = await supabase.from('messages').insert({ content: text.trim() })
40
      if (dbError) throw dbError
41
      setText('')
42
      await loadMessages()
43
    } catch (err: any) {
44
      setError(err.message)
45
    } finally {
46
      setLoading(false)
47
    }
48
  }
49

50
  useEffect(() => {
51
    void loadMessages()
52
  }, [loadMessages])
53

54
  return (
55
    <div style={{ padding: 24, maxWidth: '600px', margin: 'auto' }}>
56
      <h1>Supabase × React (Vite)</h1>
57
      <div style={{ display: 'flex', gap: 8, marginBottom: 16 }}>
58
        <input
59
          value={text}
60
          onChange={(e) => setText(e.target.value)}
61
          placeholder="输入消息"
62
          style={{ flex: 1 }}
63
        />
64
        <button onClick={insertMessage} disabled={loading}>
65
          {loading ? '提交中…' : '新增'}
66
        </button>
67
      </div>
68
      {error && <p style={{ color: 'red' }}>Error: {error}</p>}
69
      {loading && <p>Loading messages...</p>}
70
      <ul>
71
        {rows.map((r) => <li key={r.id}>#{r.id}: {r.content}</li>)}
72
      </ul>
73
    </div>
74
  )
75
}
76

77
export default App

4) 运行#

1
pnpm dev

4. 常见问题与排错#

403/401 权限错误:
- 检查 RLS 策略: 确保你的 RLS 策略允许当前操作（select, insert 等）。对于入门测试，可以使用教程中提供的宽松策略。
- 检查 API Key: 确认客户端使用的是 anon (public) key，而不是 service_role (secret) key。
连接失败:
- 核对 URL 和 Key: 仔细检查 .env 文件中的 URL 和 anon key 是否与 Supabase 项目设置中的完全一致，注意不要有空格或特殊字符。
环境变量未加载:
- 遵循命名约定: 确保变量前缀符合框架要求 (NEXT_PUBLIC_, VITE_, PUBLIC_)。
- 重启开发服务器: 修改 .env 文件后，需要重启开发服务器才能生效。
CORS 跨域问题:
- Supabase 默认已为你的 API 启用 CORS。如果你通过自定义域名或代理访问，请检查浏览器控制台的错误信息，并在 Supabase Dashboard 的 API Settings -> CORS Configuration 中添加你的访问源。

5. 后续扩展方向#

用户认证 (Auth): 探索 Supabase 强大的认证功能，如邮箱/密码登录、社交登录 (GitHub, Google)、魔法链接等。
Edge Functions: 将复杂的业务逻辑或需要安全环境的操作（如调用第三方服务、处理支付）封装在 Edge Functions 中。
实时 (Realtime): 利用 Supabase 的实时订阅功能，监听数据库变更，构建聊天、协作等动态应用。
存储 (Storage): 学习如何上传、下载和管理文件，如用户头像、文档等。

6. 附录：核心功能扩展#

用户认证 (Auth)#

Supabase 提供了强大且易于使用的认证解决方案。以下是如何在你的应用中集成基础的邮箱密码登录功能。

1) 调整 RLS 策略#

为了让登录用户能够管理自己的消息，我们需要更新 messages 表的 RLS 策略。将之前的宽松策略替换为以下更安全的版本：

1
-- 删除旧的匿名策略
2
DROP POLICY IF EXISTS "Allow anonymous read" ON public.messages;
3
DROP POLICY IF EXISTS "Allow anonymous insert" ON public.messages;
4

5
-- 创建新的基于用户的策略
6
-- 允许用户读取自己的消息
7
CREATE POLICY "Allow individual read access" ON public.messages FOR SELECT USING (auth.uid() = user_id);
8
-- 允许用户插入自己的消息
9
CREATE POLICY "Allow individual insert access" ON public.messages FOR INSERT WITH CHECK (auth.uid() = user_id);
10

11
-- 为表添加 user_id 字段
12
ALTER TABLE public.messages ADD COLUMN IF NOT EXISTS user_id UUID REFERENCES auth.users(id) ON DELETE CASCADE;

重要提示
执行此操作前，请确保你的 messages 表中已有一个 user_id 字段，用于关联 auth.users 表。如果还没有，请先添加该字段。

2) 构建认证组件#

你可以创建一个简单的认证组件，处理注册、登录和登出逻辑。以下是一个 React 示例：

1
import { useState } from 'react';
2
import { supabase } from '../lib/supabase'; // 假设你的 Supabase 客户端在这里
3

4
export default function Auth() {
5
  const [email, setEmail] = useState('');
6
  const [password, setPassword] = useState('');
7
  const [loading, setLoading] = useState(false);
8

9
  const handleLogin = async (e) => {
10
    e.preventDefault();
11
    setLoading(true);
12
    const { error } = await supabase.auth.signInWithPassword({ email, password });
13
    if (error) alert(error.message);
14
    setLoading(false);
15
  };
16

17
  const handleSignup = async (e) => {
18
    e.preventDefault();
19
    setLoading(true);
20
    const { error } = await supabase.auth.signUp({ email, password });
21
    if (error) alert(error.message);
22
    else alert('注册成功，请检查你的邮箱以激活账号！');
23
    setLoading(false);
24
  };
25

26
  return (
27
    <div>
28
      <form onSubmit={handleLogin}>
29
        <input type="email" value={email} onChange={(e) => setEmail(e.target.value)} placeholder="邮箱" />
30
        <input type="password" value={password} onChange={(e) => setPassword(e.target.value)} placeholder="密码" />
31
        <button disabled={loading}>{loading ? '处理中...' : '登录'}</button>
32
        <button onClick={handleSignup} disabled={loading}>注册</button>
33
      </form>
34
    </div>
35
  );
36
}

实时 (Realtime)#

通过 Supabase 的实时订阅，你的应用可以即时响应数据库的变化。

1
// 监听 messages 表的插入事件
2
const channel = supabase.channel('messages-channel');
3

4
channel
5
  .on('postgres_changes', { event: 'INSERT', schema: 'public', table: 'messages' }, (payload) => {
6
    console.log('New message:', payload.new);
7
    // 在这里更新你的 UI
8
  })
9
  .subscribe();
10

11
// 不再需要时，记得取消订阅
12
// supabase.removeChannel(channel);

部署指南 (Deployment Guide)#

将集成了 Supabase 的前端应用部署到 Vercel 或 Netlify 等平台非常简单，核心是正确配置环境变量。

登录你的托管平台 (Vercel, Netlify, etc.)。
导入你的 Git 仓库。
配置环境变量:
- 在项目的设置页面中，找到环境变量 (Environment Variables) 配置区域。
- 添加你在 .env.local 文件中使用的 PUBLIC_SUPABASE_URL 和 PUBLIC_SUPABASE_ANON_KEY (或对应框架的前缀)。
- 重要: 确保变量名与你的代码中的 import.meta.env 或 process.env 调用完全匹配。
触发部署。

平台会自动检测你的框架 (Next.js, Astro, Vite) 并执行正确的构建命令。部署成功后，你的应用就可以在线访问了。

1. 准备工作#

2. Supabase 项目设置#

创建项目#

准备数据库表与 RLS 策略#

配置环境变量#

3. 前端框架集成示例#

Next.js 最小可运行示例#

1) 初始化项目与依赖#

2) 创建 Supabase 客户端#

3) 在页面中读写数据#

4) 运行#

Astro 最小可运行示例#

1) 初始化项目#

2) 创建 Supabase 客户端组件#

3) 在页面中使用组件#

4) 运行#

React（Vite）最小可运行示例#

1) 初始化项目与依赖#

2) 创建 Supabase 客户端#

3) 在 App.tsx 中读写数据#

4) 运行#

4. 常见问题与排错#

5. 后续扩展方向#

6. 附录：核心功能扩展#

用户认证 (Auth)#

1) 调整 RLS 策略#

2) 构建认证组件#

实时 (Realtime)#

部署指南 (Deployment Guide)#

3) 在 `App.tsx` 中读写数据#