Supabase Edge Functions 本地开发与原理详解

本文结合实际踩坑经验，详细介绍 Supabase Edge Functions 的本地开发、部署、测试流程，并解答常见疑问，适合初学者和有 Node/Next.js 背景的开发者。

---

目录

1. 环境准备
2. 初始化 Supabase 项目
3. 启动本地 Supabase 服务
4. 创建与编写 Edge Function
5. 本地测试 Edge Function
6. 部署到 Supabase 云端
7. 常见问题与原理解答
8. 参考资料

---

环境准备

1. 安装依赖

• Node.js（推荐用 nvm 管理）
• Supabase CLI

  1brew install supabase/tap/supabase

2. 安装并启动 Docker Desktop

Supabase 本地开发依赖 Docker。

• 下载 Docker Desktop
• 安装后务必启动 Docker Desktop，直到看到“Docker Desktop is running”。

---

初始化 Supabase 项目

如果还没有 Supabase 项目目录，先新建一个：

1mkdir supabase-learn
2cd supabase-learn
3supabase init

---

启动本地 Supabase 服务

1supabase start

等待所有服务启动完成（包括数据库、API、Studio 等）。

---

创建与编写 Edge Function

1. 新建 Function

1supabase functions new hello

会在 supabase/functions/hello/ 目录下生成 index.ts 文件。

2. 编写 Function 代码（Deno 格式）

1import "jsr:@supabase/functions-js/edge-runtime.d.ts"
2
3Deno.serve(async (req) => {
4  const { name } = await req.json()
5  const data = {
6    message: `Hello ${name}!`,
7  }
8
9  return new Response(
10    JSON.stringify(data),
11    { headers: { "Content-Type": "application/json" } }
12  )
13})

⚠️ Supabase Edge Functions 只能用 Deno 语法，不能用 Node.js/Express 语法。

---

本地测试 Edge Function

1. 启动本地 Function 服务

确保 Docker 已启动，然后运行：

1supabase functions serve hello

你会看到类似输出：

1Serving "hello" at http://127.0.0.1:54321/functions/v1/hello

2. 正确测试方法

Edge Functions 默认需要 Authorization 头，不能直接在浏览器访问！

用 curl 测试

1curl -i --location --request POST 'http://127.0.0.1:54321/functions/v1/hello' \
2  --header 'Authorization: Bearer <你的本地 JWT>' \
3  --header 'Content-Type: application/json' \
4  --data '{"name":"Functions"}'

<你的本地 JWT> 可用 Supabase CLI 文档里的示例，或在项目设置中获取。

用 Postman 测试

• Method: POST
• URL: http://127.0.0.1:54321/functions/v1/hello
• Headers:
  • Authorization: Bearer <你的本地 JWT>
  • Content-Type: application/json
• Body: {"name":"Functions"}

用 fetch 代码测试

1fetch('http://127.0.0.1:54321/functions/v1/hello', {
2  method: 'POST',
3  headers: {
4    'Content-Type': 'application/json',
5    'Authorization': 'Bearer <你的本地 JWT>'
6  },
7  body: JSON.stringify({ name: 'Functions' })
8})
9  .then(res => res.json())
10  .then(console.log)

---

部署到 Supabase 云端

1. 登录 Supabase 账号

1supabase login

2. 关联云端项目

在 Supabase 控制台找到你的 Project Ref（项目设置 > Project Reference），然后：

1supabase link --project-ref <your-project-ref>

project id 在以下途径找到:

3. 部署 Function

1supabase functions deploy hello

部署成功后，可以在 Supabase 控制台的 Functions 页面看到。

---

常见问题与原理解答

Q1. 为什么不能用 Node.js/Express 语法写 Edge Function？

• Supabase Edge Functions 目前只支持 Deno 运行时，不支持 Node.js/Express 语法。
• 你必须用 Deno 的 API（如 Deno.serve）来写函数。

Q2. Edge Functions 和 Next.js API 路由有什么区别？

Next.js API 路由	Supabase Edge Functions
运行在 Node.js/Vercel	运行在 Supabase Edge Runtime（Deno）
适合项目内部 API	适合安全、全局低延迟、与 Supabase 深度集成的后端逻辑
不是边缘计算（除非用 Edge Runtime）	真正的边缘节点运行
不能直接用 Supabase 服务	可无缝访问 Supabase 数据库、认证等

Q3. Edge Functions 的最大作用是什么？

• 边缘计算：让后端逻辑离用户更近，全球低延迟。
• 安全隔离：处理密钥、签名、第三方 API 调用等敏感逻辑。
• 无服务器：按需运行，无需维护服务器。
• 与 Supabase 服务深度集成：直接操作数据库、认证、存储等。

Q4. 为什么不能直接在浏览器访问 Edge Function？

• Edge Function 默认需要 Authorization 头，浏览器地址栏无法加头部。
• 推荐用 curl、Postman 或 fetch 代码测试。

Q5. supabase/config.toml 是什么？要怎么配置？

• 这是 Supabase 项目的主配置文件，管理本地和云端的各种参数（如认证、数据库、端口等）。
• 一般默认配置即可用，只有有特殊需求时才需手动修改。
• 配置项详见官方文档。

---

参考资料

• Supabase 官方文档
• Supabase Edge Functions 指南
• Deno 官方文档
• Supabase CLI 文档

---

如有更多问题，欢迎留言交流！