Supabase CLI 本地开发与数据库操作指南

这份指南涵盖了如何使用 Supabase CLI 在现有项目中搭建本地开发环境，并管理 PostgreSQL 数据库结构。

一、环境准备与安装

依赖项	说明
Docker	必须安装并运行。 Supabase CLI 使用 Docker 容器来运行本地 PostgreSQL、Auth、Storage 等服务。
Supabase CLI	命令行工具，用于管理本地环境和迁移。

1. 安装 Supabase CLI

请根据你的操作系统选择相应的安装方式：

• macOS / Linux (推荐 Homebrew):

  brew install supabase/cli/supabase
  

• Windows (推荐 Scoop):

  或直接使用二进制文件，放到 c:\Windows\System32 下。我是使用阿里云定制的修改版本，他们直接提供二进制文件。

  scoop install supabase
  

• 安装验证： 安装完成后，请重启终端，并执行以下命令验证是否安装成功：

  supabase --version
  

2. 安装 Supabase JavaScript 客户端库 (用于 Vue 项目)

在你的 Vue 项目根目录中使用 pnpm 安装 Supabase 客户端库：

pnpm install @supabase/supabase-js

---

二、本地环境启动

在你的 Vue 项目根目录 执行以下步骤来启动本地 Supabase 服务：

1. 初始化 Supabase 配置

此命令会在你的项目目录下创建 supabase/ 文件夹，包含配置文件和迁移目录。如果另一台电脑上重新拉这个项目，不要执行如下命令。

supabase init

2. 启动本地服务 (需要 Docker 运行)

此命令会启动本地所有的 Supabase 依赖服务（PostgreSQL, Auth, Realtime, Storage）。如果已经存在的项目，重新拉下来，直接在项目根目录，直接 supabase start。

supabase start

输出信息	目的/用途
API URL	你的 Vue 客户端代码需要连接的本地地址（通常是 http://localhost:54321）。
Studio URL	本地数据库管理界面的访问地址（通常是 http://localhost:54323）。

提示： 如果你只在本地开发，可以跳过 supabase login。只有当你需要同步到远程 Supabase 项目时才需要登录。

---

三、数据库结构管理 (迁移 Migrations)

使用数据库迁移是管理 PostgreSQL 表结构的标准方式。

1. 创建一个新的迁移文件

当你需要进行任何数据库结构变更时（创建表、添加列、修改约束等），都应该创建一个新的迁移文件：

supabase migration new <你的变更描述>
# 示例：supabase migration new create_initial_users_table

此命令会在 supabase/migrations 目录下生成一个带时间戳的 .sql 文件。

2. 编写 SQL 变更语句

打开新创建的 .sql 文件，写入你的 DDL (数据定义语言) 语句。

• 初始建表示例：

  CREATE TABLE public.users (
      id uuid NOT NULL DEFAULT gen_random_uuid(),
      email text NOT NULL UNIQUE,
      created_at timestamp with time zone DEFAULT now(),
      CONSTRAINT users_pkey PRIMARY KEY (id)
  );
  -- 记得启用 RLS：
  ALTER TABLE public.users ENABLE ROW LEVEL SECURITY;
  

• 后续修改示例 (添加列)：

  ALTER TABLE public.users ADD COLUMN phone_number text NULL;
  -- 如果需要填充数据，可以在这里加入 UPDATE 语句 (DML)
  

3. 应用迁移到本地数据库

执行以下命令来应用你的所有迁移文件到本地 PostgreSQL 数据库：

supabase db reset

db reset 警告： 它会清空并重建本地数据库，然后从头执行所有迁移文件。这是本地开发的推荐方式，但切勿在生产环境使用。

---

☁️ 四、同步到远程 Supabase 项目

当你完成本地测试，准备将数据库结构部署到远程（例如阿里云上）的 Supabase 实例时，需要进行同步：

1. 登录与链接项目

阿里云的有自己的文档，可以参考一下。

# 登录 Supabase 账户
supabase login

# 链接到你的远程项目 (使用 Project ID)
supabase link --project-ref <你的 Project ID>

CLI 会要求你输入远程数据库密码。

2. 推送迁移文件

将本地 supabase/migrations 目录中未被远程数据库执行的变更推送上去。

supabase db push

CLI 会让你确认将要执行的 SQL 语句。确认后，远程数据库结构就会更新。