Tóm tắt
Supabase CLI chạy một ngăn xếp Supabase hoàn chỉnh trên máy của bạn bằng Docker: PostgreSQL, Auth, Storage và Edge Functions. Cài đặt nó bằng brew install supabase/tap/supabase, chạy supabase init và supabase start để khởi động môi trường cục bộ, sau đó sử dụng supabase db push và supabase functions deploy để triển khai lên môi trường sản xuất. Đây là cách nhanh nhất để xây dựng và kiểm tra backend Supabase mà không cần chạm vào đám mây.
Giới thiệu
73% lỗi backend bị phát hiện trong môi trường sản xuất vì các nhà phát triển bỏ qua việc kiểm thử cục bộ. Với Supabase CLI, điều đó không còn là lý do biện minh nữa. Bạn sẽ có một môi trường tương đương sản xuất đầy đủ chạy trên máy của mình chỉ trong vòng chưa đầy 5 phút.
Đây là vấn đề thực sự: hầu hết các nhà phát triển hoặc kiểm thử trực tiếp trên môi trường sản xuất (rủi ro) hoặc dành hàng giờ để cấu hình các môi trường cục bộ không bao giờ khớp hoàn toàn với đám mây (gây khó chịu). Supabase CLI giải quyết cả hai vấn đề này. Nó cung cấp cho bạn một ngăn xếp cục bộ dựa trên Docker mô phỏng chính xác môi trường sản xuất, vì vậy những gì hoạt động cục bộ sẽ hoạt động trên môi trường sản xuất.
Kiểm thử API Supabase của bạn với Apidog - miễn phí
Đến cuối hướng dẫn này, bạn sẽ có thể:
- Thiết lập một môi trường Supabase cục bộ hoàn chỉnh trong vài phút
- Quản lý các thay đổi schema cơ sở dữ liệu bằng các migration được kiểm soát phiên bản
- Xây dựng và kiểm thử Edge Functions cục bộ trước khi triển khai
- Triển khai lên môi trường sản xuất chỉ với một lệnh duy nhất
Tại sao phát triển Supabase cục bộ bị lỗi nếu không có CLI
Nếu bạn đã từng cố gắng xây dựng một ứng dụng Supabase mà không có CLI, bạn sẽ hiểu được nỗi đau đó. Dưới đây là ba kịch bản thường xuyên xảy ra.
Cái bẫy "kiểm thử trên môi trường sản xuất". Bạn thực hiện thay đổi schema trực tiếp trong bảng điều khiển Supabase. Nó hoạt động. Bạn đẩy frontend của mình. Ba ngày sau, một đồng đội kéo repo và ứng dụng của họ bị lỗi vì cơ sở dữ liệu của họ không có cột mới đó.
Sự không khớp môi trường. Bạn thiết lập một phiên bản PostgreSQL cục bộ, tạo lại schema Supabase của mình theo cách thủ công và dành hai giờ để gỡ lỗi tại sao các chính sách Bảo mật Cấp độ Dòng (RLS) lại hoạt động khác nhau cục bộ. Chúng không hoạt động khác nhau. Bạn đã bỏ sót một chính sách.
Vấn đề "chạy được trên máy của tôi". Edge Function của bạn hoạt động trong trình chỉnh sửa bảng điều khiển Supabase nhưng lại thất bại trên môi trường sản xuất vì bạn đã kiểm thử với các giá trị được mã hóa cứng thay vì các biến môi trường thực tế.
Đây không phải là những trường hợp cá biệt. Sai lệch schema (cơ sở dữ liệu cục bộ và từ xa không đồng bộ) là vấn đề số 1 được báo cáo đối với các nhóm sử dụng Supabase. CLI khắc phục cả ba vấn đề:
- Các Migration giữ cho các thay đổi schema được kiểm soát phiên bản và có thể tái tạo
- Ngăn xếp Docker cục bộ mô phỏng chính xác môi trường sản xuất, cùng phiên bản PostgreSQL, cùng công cụ RLS
- Chức năng phục vụ cục bộ kiểm thử Edge Functions với các biến môi trường thực tế
Supabase CLI hoạt động như thế nào
Ngăn xếp cục bộ
Khi bạn chạy supabase start, CLI sẽ khởi động một ngăn xếp Docker Compose với các dịch vụ này:
| Dịch vụ | Cổng | Mục đích |
|---|---|---|
| PostgreSQL | 54322 | Cơ sở dữ liệu của bạn |
| PostgREST | 54321 | API REST tự động tạo |
| GoTrue | 54321/auth | Dịch vụ xác thực |
| Realtime | 54321/realtime | Các gói đăng ký WebSocket |
| Storage | 54321/storage | Lưu trữ tệp |
| Studio | 54323 | Bảng điều khiển trực quan |
| Inbucket | 54324 | Kiểm thử email (nhận tất cả email cục bộ) |
| Edge Runtime | 54321/functions | Trình chạy hàm dựa trên Deno |
Đây là ngăn xếp tương tự đang chạy trong Supabase Cloud. Trên máy của bạn.
Cài đặt
macOS:
brew install supabase/tap/supabase
Windows (Scoop):
scoop bucket add supabase https://github.com/supabase/scoop-bucket.git
scoop install supabase
Linux / npm:
npm install -g supabase
Xác minh đã hoạt động:
supabase --version
# supabase 1.x.x
supabase startThiết lập dự án
mkdir my-project && cd my-project
supabase init
Điều này tạo ra:
supabase/
├── config.toml # Cổng, cài đặt auth, cấu hình lưu trữ
├── seed.sql # Dữ liệu phát triển được tải mỗi khi reset db
└── migrations/ # Lịch sử phiên bản schema
Khởi động ngăn xếp cục bộ
supabase start
Lần chạy đầu tiên tải xuống khoảng 1GB hình ảnh Docker. Sau đó, việc khởi động mất khoảng 10 giây.
API URL: http://localhost:54321
DB URL: postgresql://postgres:postgres@localhost:54322/postgres
Studio: http://localhost:54323
anon key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Sao chép anon key vào tệp .env.local của bạn. Bạn sẽ cần nó cho frontend của mình.
Quản lý cơ sở dữ liệu với migration
Migration là cốt lõi của quy trình làm việc CLI. Mọi thay đổi schema đều trở thành một tệp SQL được kiểm soát phiên bản và được theo dõi trong Git. Không còn "ai đã thay đổi cơ sở dữ liệu và khi nào" nữa.
Tạo migration đầu tiên của bạn
supabase migration new create_posts_table
# Tạo: supabase/migrations/20260324120000_create_posts_table.sql
Chỉnh sửa tệp:
-- Tạo bảng bài viết với RLS ngay từ đầu
CREATE TABLE posts (
id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
user_id UUID REFERENCES auth.users(id) ON DELETE CASCADE NOT NULL,
title TEXT NOT NULL,
content TEXT,
published BOOLEAN DEFAULT false,
created_at TIMESTAMPTZ DEFAULT NOW(),
updated_at TIMESTAMPTZ DEFAULT NOW()
);
-- Bật Bảo mật Cấp độ Dòng (Row Level Security)
ALTER TABLE posts ENABLE ROW LEVEL SECURITY;
-- Bất kỳ ai cũng có thể đọc các bài viết đã xuất bản
CREATE POLICY "Anyone can read published posts"
ON posts FOR SELECT
USING (published = true);
-- Người dùng quản lý bài viết của riêng họ
CREATE POLICY "Users manage own posts"
ON posts FOR ALL
USING (auth.uid() = user_id);
-- Tự động cập nhật updated_at trên mỗi thay đổi
CREATE OR REPLACE FUNCTION update_updated_at()
RETURNS TRIGGER AS $$
BEGIN
NEW.updated_at = NOW();
RETURN NEW;
END;
$$ LANGUAGE plpgsql;
CREATE TRIGGER posts_updated_at
BEFORE UPDATE ON posts
FOR EACH ROW EXECUTE FUNCTION update_updated_at();
Áp dụng nó:
supabase migration up
Tạo các kiểu TypeScript
Sau mỗi thay đổi schema, hãy tạo lại các kiểu của bạn:
supabase gen types typescript --local > src/types/database.ts
Frontend của bạn có được tính an toàn kiểu đầy đủ:
import { Database } from '@/types/database'
type Post = Database['public']['Tables']['posts']['Row']
type NewPost = Database['public']['Tables']['posts']['Insert']
// Bây giờ trình chỉnh sửa của bạn phát hiện lỗi kiểu trước khi chạy
const createPost = async (post: NewPost) => {
const { data, error } = await supabase
.from('posts')
.insert(post)
.select()
.single()
return data
}
Gieo dữ liệu phát triển
Chỉnh sửa supabase/seed.sql:
-- Người dùng thử nghiệm (bỏ qua xác thực cho phát triển cục bộ)
INSERT INTO auth.users (id, email) VALUES
('00000000-0000-0000-0000-000000000001', 'alice@example.com'),
('00000000-0000-0000-0000-000000000002', 'bob@example.com');
-- Bài viết thử nghiệm
INSERT INTO posts (user_id, title, content, published) VALUES
('00000000-0000-0000-0000-000000000001', 'Bắt đầu với Supabase', 'Đây là những gì tôi đã học...', true),
('00000000-0000-0000-0000-000000000002', 'Bản nháp: Các mẫu thiết kế API', 'Đang trong quá trình...', false);
Đặt lại và gieo lại bất cứ lúc nào:
supabase db reset
Lệnh này sẽ xóa mọi thứ, chạy lại tất cả các migration và tải dữ liệu hạt giống của bạn. Chạy nó mỗi sáng để bắt đầu lại từ đầu.
Kiểm thử API Supabase với Apidog
Khi Supabase cục bộ của bạn đang chạy, bạn có một API REST hoạt động đầy đủ tại http://localhost:54321. Supabase tự động tạo các endpoint cho mọi bảng thông qua PostgREST. Việc kiểm thử thủ công những thứ này bằng curl sẽ nhanh chóng trở nên tẻ nhạt, đặc biệt khi bạn cần kiểm thử các chính sách RLS với các mã thông báo người dùng khác nhau.
Apidog kết nối trực tiếp với phiên bản Supabase cục bộ của bạn. Bạn có thể:
- Lưu các yêu cầu dưới dạng các bộ sưu tập có thể tái sử dụng
- Kiểm thử cùng một endpoint với tư cách là những người dùng khác nhau bằng cách chuyển đổi môi trường
- Thêm các xác nhận ("phản hồi chứa ít nhất 1 bài viết") và chạy chúng dưới dạng một bộ kiểm thử
- Tự động chia sẻ tài liệu API với nhóm của bạn
Thiết lập Apidog với Supabase cục bộ:
- Tạo một dự án mới trong Apidog
- Đặt URL cơ sở:
http://localhost:54321 - Thêm biến môi trường:
anon_key = your-local-anon-key - Thêm tiêu đề Authorization:
Bearer {{anon_key}}
Kiểm thử endpoint bài viết:
GET http://localhost:54321/rest/v1/posts?published=eq.true
Authorization: Bearer {{anon_key}}
apikey: {{anon_key}}
Lưu yêu cầu này, thêm xác nhận rằng phản hồi chứa ít nhất một bài viết và chạy nó mỗi khi bạn thay đổi chính sách RLS của mình. Bạn sẽ bắt được các chính sách bị lỗi trước khi chúng đến môi trường sản xuất.
Bắt đầu kiểm thử API Supabase của bạn với Apidog
Edge Functions: xây dựng và kiểm thử cục bộ
Edge Functions chạy trên Deno ở biên, gần với người dùng của bạn. Chúng hoàn hảo cho các webhook, công việc nền và các endpoint API cần logic phía máy chủ.
Tạo một hàm
supabase functions new send-welcome-email
Điều này tạo ra supabase/functions/send-welcome-email/index.ts:
import { serve } from 'https://deno.land/std@0.168.0/http/server.ts'
import { createClient } from 'https://esm.sh/@supabase/supabase-js@2'
serve(async (req) => {
const { user_id } = await req.json()
// Service role bỏ qua RLS - sử dụng cẩn thận
const supabase = createClient(
Deno.env.get('SUPABASE_URL')!,
Deno.env.get('SUPABASE_SERVICE_ROLE_KEY')!
)
const { data: profile } = await supabase
.from('profiles')
.select('email, full_name')
.eq('id', user_id)
.single()
// Logic gửi email của bạn ở đây
console.log(`Đang gửi email chào mừng tới ${profile?.email}`)
return new Response(
JSON.stringify({ success: true }),
{ headers: { 'Content-Type': 'application/json' } }
)
})
Kiểm thử cục bộ với hot reload
supabase functions serve
Máy chủ hàm theo dõi các thay đổi tệp và tự động tải lại. Kiểm thử nó:
curl -X POST http://localhost:54321/functions/v1/send-welcome-email \
-H "Authorization: Bearer YOUR_ANON_KEY" \
-H "Content-Type: application/json" \
-d '{"user_id": "00000000-0000-0000-0000-000000000001"}'
Triển khai lên môi trường sản xuất
# Triển khai một hàm
supabase functions deploy send-welcome-email
# Triển khai tất cả các hàm
supabase functions deploy
Các kỹ thuật nâng cao và phương pháp đã được chứng minh
Quản lý bí mật
Không bao giờ mã hóa cứng các khóa API trong các hàm của bạn. Sử dụng bí mật:
# Đặt các bí mật sản xuất
supabase secrets set RESEND_API_KEY=re_xxx STRIPE_KEY=sk_live_xxx
# Liệt kê tất cả các bí mật
supabase secrets list
# Xóa một bí mật
supabase secrets unset STRIPE_KEY
Truy cập chúng trong các hàm:
const resendKey = Deno.env.get('RESEND_API_KEY')
// Không bao giờ: const resendKey = 're_xxx'
Phân nhánh cơ sở dữ liệu
Đang thực hiện một thay đổi schema lớn? Tạo một nhánh độc lập:
supabase branches create feature-payments
supabase branches switch feature-payments
# Thực hiện thay đổi, kiểm thử, sau đó hợp nhất
supabase branches merge feature-payments
Điều này giữ cho cơ sở dữ liệu phát triển chính của bạn sạch sẽ trong khi bạn thử nghiệm.
Những lỗi thường gặp cần tránh
Chỉnh sửa trực tiếp cơ sở dữ liệu trong Studio. Luôn sử dụng migration. Các chỉnh sửa trực tiếp không được theo dõi và đồng đội của bạn sẽ không có chúng.
Commit các tệp .env. Sử dụng supabase secrets set cho môi trường sản xuất. Thêm .env* vào .gitignore của bạn.
Bỏ qua supabase db reset sau khi pull. Khi bạn pull các thay đổi của đồng đội, các migration mới của họ cần phải chạy cục bộ. Reset để áp dụng chúng.
Không tạo lại các kiểu sau khi thay đổi schema. Các kiểu TypeScript của bạn sẽ lỗi thời ngay khi bạn thêm một cột. Hãy biến việc tạo kiểu thành một phần của quy trình làm việc migration của bạn.
Triển khai các hàm mà không kiểm thử cục bộ. Luôn chạy supabase functions serve và kiểm thử với các yêu cầu thực tế trước khi triển khai.
Sử dụng khóa vai trò dịch vụ trong mã frontend. Khóa vai trò dịch vụ bỏ qua RLS. Nó chỉ thuộc về Edge Functions và mã phía máy chủ, không bao giờ trong trình duyệt của bạn.
Mẹo tối ưu hiệu suất
# Bỏ qua các dịch vụ bạn không cần để tiết kiệm bộ nhớ
supabase start --exclude-studio --exclude-inbucket
# Kiểm tra những gì đang sử dụng tài nguyên
docker stats
Các lựa chọn thay thế và so sánh
| Tính năng | Supabase CLI | Firebase CLI | PlanetScale CLI |
|---|---|---|---|
| Cơ sở dữ liệu cục bộ | PostgreSQL đầy đủ | Chỉ trình giả lập | Chỉ đám mây |
| Migration | Tệp SQL trong Git | Không hỗ trợ gốc | Phân nhánh |
| Edge Functions | Thời gian chạy Deno | Cloud Functions | Không bao gồm |
| Xác thực cục bộ | GoTrue đầy đủ | Trình giả lập | Không bao gồm |
| Mã nguồn mở | Hoàn toàn mở | Độc quyền | Độc quyền |
| Tạo kiểu | Tích hợp sẵn | Thủ công | Thủ công |
Trình giả lập cục bộ của Firebase tốt cho việc tạo mẫu nhanh nhưng không cung cấp cho bạn một phiên bản PostgreSQL thực sự. Mô hình phân nhánh của PlanetScale rất tuyệt vời cho các thay đổi schema nhưng bạn luôn phải làm việc với đám mây. Supabase CLI thắng thế đối với các nhóm muốn có trải nghiệm phát triển cục bộ hoàn toàn mã nguồn mở, gốc PostgreSQL.
Các trường hợp sử dụng thực tế
Ứng dụng SaaS với dữ liệu đa đối tượng thuê. Một công ty khởi nghiệp fintech quản lý 47 migration trên ba môi trường (dev, staging, prod). Các chính sách RLS được kiểm thử cục bộ với các vai trò người dùng khác nhau trước khi bất kỳ mã nào được đưa vào môi trường sản xuất. Kết quả: không có sự cố sản xuất nào liên quan đến schema trong sáu tháng.
Xử lý đơn hàng thương mại điện tử. Một nhóm thương mại điện tử sử dụng Edge Functions để xử lý webhook Stripe. Họ kiểm thử các payload webhook cục bộ bằng cách sử dụng supabase functions serve với các sự kiện kiểm thử Stripe thực tế. Thời gian triển khai giảm từ 2 giờ xuống còn 15 phút.
Backend ứng dụng di động. Một nhóm React Native tạo các kiểu TypeScript sau mỗi migration và chia sẻ chúng dưới dạng một gói npm nội bộ. Frontend và backend tự động đồng bộ. Không còn các câu hỏi "endpoint này trả về những trường nào?" trong Slack nữa.
Tổng kết
Đây là những gì bạn có thể làm ngay bây giờ:
- Thiết lập một môi trường Supabase cục bộ hoàn chỉnh trong vài phút
- Sử dụng migration để kiểm soát phiên bản mọi thay đổi schema
- Kiểm thử Edge Functions cục bộ với hot reload
- Tự động tạo các kiểu TypeScript từ schema của bạn
- Triển khai với
supabase db pushvàsupabase functions deploy - Kiểm thử API của bạn với Apidog trước khi triển khai lên môi trường sản xuất
Quy trình làm việc này mang lại hiệu quả ngay lập tức. Nhóm của bạn triển khai nhanh hơn, phát hiện lỗi sớm hơn và không bao giờ phải đối phó với sự sai lệch schema nữa.
Các bước tiếp theo của bạn:
- Cài đặt:
brew install supabase/tap/supabase - Chạy
supabase inittrong dự án của bạn - Tạo migration đầu tiên của bạn
- Thiết lập Apidog để kiểm thử các endpoint cục bộ của bạn
- Triển khai lên môi trường sản xuất một cách tự tin
Kiểm thử API Supabase của bạn với Apidog - miễn phí
Câu hỏi thường gặp
Tôi có cần Docker để sử dụng Supabase CLI không?Có. Docker Desktop phải đang chạy trước khi supabase start. CLI sử dụng Docker Compose để chạy toàn bộ ngăn xếp cục bộ. Nếu Docker không chạy, bạn sẽ nhận được lỗi "Cannot connect to Docker daemon".
Làm cách nào để đồng bộ hóa cơ sở dữ liệu cục bộ của tôi với môi trường sản xuất?Sử dụng supabase db pull để tạo migration từ schema từ xa của bạn, sau đó supabase db push để áp dụng các migration cục bộ lên môi trường sản xuất. Chạy supabase db reset cục bộ sau khi pull để đảm bảo môi trường của bạn khớp.
Tôi có thể sử dụng Supabase CLI mà không cần tài khoản Supabase Cloud không?Có. Bạn có thể sử dụng CLI hoàn toàn cục bộ để phát triển mà không cần tài khoản đám mây. Bạn chỉ cần supabase login và supabase link khi bạn sẵn sàng triển khai lên môi trường sản xuất.
Làm cách nào để xử lý xung đột migration trong một nhóm?Kéo các thay đổi Git mới nhất và chạy supabase db reset trước khi tạo migration mới. Sử dụng tên migration mô tả và trao đổi với nhóm của bạn khi thực hiện các thay đổi schema gây phá vỡ.
Sự khác biệt giữa supabase db push và supabase migration up là gì?supabase migration up áp dụng các migration đang chờ xử lý vào cơ sở dữ liệu cục bộ của bạn. supabase db push áp dụng chúng vào dự án từ xa (sản xuất) của bạn. Luôn kiểm thử cục bộ trước.
Tôi có thể sử dụng Supabase CLI với một dự án hiện có không?Có. Chạy supabase link --project-ref YOUR_PROJECT_ID để liên kết với một dự án hiện có, sau đó supabase db pull để tạo migration từ schema từ xa hiện tại của bạn.
Làm cách nào để kiểm thử các chính sách RLS cục bộ?Sử dụng Supabase Studio tại http://localhost:54323 để chuyển đổi giữa các vai trò người dùng hoặc kiểm thử qua API với các mã thông báo JWT khác nhau. Apidog giúp việc này dễ dàng: tạo nhiều môi trường với các mã thông báo người dùng khác nhau và chạy cùng các yêu cầu với tư cách là những người dùng khác nhau.
Supabase CLI có miễn phí không?Có. CLI là miễn phí và mã nguồn mở. Phát triển cục bộ không tốn chi phí. Bạn chỉ trả tiền cho các tài nguyên Supabase Cloud khi bạn triển khai lên môi trường sản xuất.