Supabase CLI 全面教程：常用 API 串联与实战指南

程序员小jobleap
8 阅读1分钟

大家好，我是jobleap.cn的小九。

一、教程前置说明

Supabase CLI 是 Supabase 官方命令行工具，能让你在 macOS 终端完成项目初始化、数据库管理、函数部署等全流程操作。 适用人群：macOS 下的前端/后端开发新手、想本地化开发 Supabase 项目的开发者 前置条件：

  • macOS 10.15+（Catalina 及以上版本）
  • 已安装 Node.js（v16+，可选，仅辅助验证）
  • 拥有 Supabase 账号（免费注册：supabase.com/）

二、环境准备：macOS 安装 Supabase CLI

1. 安装 Homebrew（若未安装）

macOS 下推荐通过 Homebrew 安装 Supabase CLI，先确保 Homebrew 已安装：

# 安装 Homebrew（一行命令完成）
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 验证 Homebrew 安装
brew -v

2. 安装 Supabase CLI

# 添加 Supabase 官方 tap 源（首次安装需执行）
brew tap supabase/tap

# 安装 Supabase CLI
brew install supabase/tap/supabase

# 验证安装（输出版本号即成功）
supabase -v

3. 升级 Supabase CLI（后续更新用）

# 更新 Homebrew 源
brew update

# 升级 Supabase CLI
brew upgrade supabase

4. 登录 Supabase 账号

# 触发浏览器登录授权（macOS 会自动打开默认浏览器）
supabase login

登录成功后，终端会提示 Logged in to Supabase CLI，此时 CLI 已关联你的 Supabase 账号。

三、核心基础操作：macOS 本地开发流程

1. 初始化本地 Supabase 项目

# 1. 创建并进入项目目录（macOS 通用路径写法）
mkdir -p ~/Projects/my-supabase-project && cd ~/Projects/my-supabase-project

# 2. 初始化 Supabase 项目（生成 .supabase 配置文件夹）
supabase init

执行后，项目目录会生成 .supabase/config.toml（核心配置文件），可直接编辑调整本地服务端口等参数。

2. 启动本地 Supabase 服务

# 启动本地全量服务（数据库、认证、存储、函数等）
supabase start

macOS 下启动成功后，终端会输出关键信息（需保存）：

  • API URL：http://localhost:54321
  • DB URL：postgresql://postgres:postgres@localhost:54322/postgres
  • 本地控制台：http://localhost:54323（可直接在浏览器打开）

3. 停止/重启本地服务

# 停止本地服务（保留数据，macOS 下数据存放在 ~/.supabase/volumes）
supabase stop

# 停止并清空本地数据（彻底重置）
supabase stop --no-backup

# 重启本地服务
supabase restart

四、macOS 下常用 API/命令实战

1. 数据库操作（核心高频）

（1）执行 SQL 脚本

# 方式1：直接执行单行 SQL（macOS 终端支持换行，用 \ 分隔）
supabase db query "CREATE TABLE users (
  id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
  name TEXT NOT NULL,
  email TEXT UNIQUE NOT NULL,
  created_at TIMESTAMP DEFAULT NOW()
);"

# 方式2：执行本地 SQL 文件（macOS 路径示例）
# 先创建 sql 目录并写入建表语句
mkdir -p ~/Projects/my-supabase-project/sql
echo "INSERT INTO users (name, email) VALUES ('Mac用户', 'mac@example.com');" > ~/Projects/my-supabase-project/sql/insert.sql

# 执行 SQL 文件
supabase db query -f ~/Projects/my-supabase-project/sql/insert.sql

（2）数据库备份与恢复（macOS 本地文件操作）

# 备份本地数据库到桌面
supabase db dump -f ~/Desktop/supabase-backup.sql

# 从桌面备份文件恢复
supabase db restore ~/Desktop/supabase-backup.sql

（3）同步远程/本地数据库

# 将 Supabase 远程项目的数据库同步到本地
supabase db pull

# 将本地数据库变更推送到远程（需先关联远程项目）
supabase db push

2. 认证管理（用户操作）

# 1. 创建测试用户
supabase auth create-user --email "mac-test@example.com" --password "Mac123456!"

# 2. 列出所有用户（macOS 终端会格式化输出表格）
supabase auth list-users

# 3. 删除指定用户（替换为实际用户 ID）
supabase auth delete-user --id "xxxx-xxxx-xxxx-xxxx"

3. 存储管理（macOS 文件上传/下载）

# 1. 创建公共存储桶
supabase storage create-bucket --name "mac-avatars" --public

# 2. 上传本地图片到存储桶（macOS 桌面文件示例）
supabase storage upload ~/Desktop/avatar.png mac-avatars/user-avatar.png

# 3. 下载存储桶文件到桌面
supabase storage download mac-avatars/user-avatar.png ~/Desktop/downloaded-avatar.png

# 4. 删除存储桶文件
supabase storage delete mac-avatars/user-avatar.png

4. Edge Functions 部署（macOS 专属优化）

# 1. 创建 Edge Function
supabase functions new hello-mac

# 2. 本地运行函数（macOS 下自动监听端口）
supabase functions serve hello-mac --port 54324

# 3. 部署函数到远程
supabase functions deploy hello-mac

# 4. 查看已部署函数
supabase functions list

五、macOS 实战串联：完整开发流程

1. 目标

创建本地项目 → 建表插数据 → 部署到远程 → 验证远程访问

2. 分步操作（复制即可执行）

# 步骤1：创建并进入项目目录
mkdir -p ~/Projects/supabase-mac-demo && cd ~/Projects/supabase-mac-demo

# 步骤2：初始化并启动本地服务
supabase init
supabase start

# 步骤3：创建并执行 SQL 脚本
echo "
CREATE TABLE IF NOT EXISTS mac_users (
  id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
  username TEXT NOT NULL,
  created_at TIMESTAMP DEFAULT NOW()
);
INSERT INTO mac_users (username) VALUES ('mac_dev1'), ('mac_dev2');
" > sql/init.sql

supabase db query -f sql/init.sql

# 步骤4：验证本地数据
supabase db query "SELECT * FROM mac_users;"

# 步骤5：关联远程项目（替换为你的项目 ref，网页端项目设置中获取）
supabase link --project-ref your-project-ref

# 步骤6：推送本地变更到远程
supabase db push

# 步骤7：验证远程访问（替换为你的项目 ref 和 anon key）
curl 'https://your-project-ref.supabase.co/rest/v1/mac_users' \
  -H "apikey: your-anon-key" \
  -H "Authorization: Bearer your-anon-key"

六、macOS 下常见问题与解决

  1. 启动服务报错：端口被占用 解决：macOS 下先查占用端口的进程，再关闭：

    # 查看 54321 端口占用进程
lsof -i :54321

# 杀死进程（替换 PID 为查询结果中的进程号）
kill -9 PID

  2. brew install supabase 失败 解决：更新 Homebrew 并修复依赖：

    brew update && brew upgrade
brew doctor # 检查并修复 Homebrew 问题
brew reinstall supabase/tap/supabase

  3. 终端提示 "command not found: supabase" 解决：将 Homebrew 路径加入环境变量（macOS 新版默认在 /opt/homebrew/bin）：

    # 临时生效
export PATH="/opt/homebrew/bin:$PATH"

# 永久生效（写入 ~/.zshrc，macOS 新版默认 shell 是 zsh）
echo 'export PATH="/opt/homebrew/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

总结

  1. macOS 安装核心：优先通过 Homebrew 安装/升级 Supabase CLI，需确保 Homebrew 路径加入系统环境变量。
  2. 本地开发关键：supabase init → supabase start 是本地开发的基础，数据默认存放在 ~/.supabase/volumes。
  3. macOS 专属优化：终端可直接操作本地文件（如桌面 ~/Desktop），端口占用可通过 lsof 命令排查，环境变量需适配 zsh（新版 macOS 默认 shell）。

这份教程覆盖了 macOS 下 Supabase CLI 的全核心操作，你可直接复制命令执行，所有路径和操作均适配 macOS 系统特性。

avatar
文章
阅读
粉丝