本文旨在解决在 Supabase Edge Function 中遇到的跨域资源共享（CORS）错误，特别是当函数在本地正常运行但在生产环境失败时。文章将详细阐述如何在 Edge Function 中正确配置 CORS 头部，处理预检请求，并强调本地 Supabase Docker 环境与 CLI 同步的重要性，这是解决此类生产环境问题的一个常见但易被忽视的关键步骤。
理解 CORS 与 Supabase Edge Function
跨域资源共享（CORS）是一种浏览器安全机制，旨在防止网页从不同源（协议、域名、端口不同）加载资源时出现安全问题。当您的前端应用（例如，运行在 app.example.com）尝试调用部署在 Supabase Edge Function（例如，运行在 functions.supabase.com）上的函数时，由于它们属于不同源，浏览器会强制执行 CORS 策略。如果没有正确配置，浏览器将阻止请求并报告 CORS 错误，如 Cross-Origin Request Blocked: The Same Origin Policy disallows reading the remote resource。
Supabase Edge Function 运行在 Deno 环境中，因此您需要像处理任何 HTTP 服务一样，在函数代码中显式地设置 CORS 响应头。
在 Edge Function 中实现 CORS
为了让浏览器能够成功调用您的 Edge Function，您需要确保以下几点：
- 处理 OPTIONS 预检请求：对于一些复杂的跨域请求（例如，带有自定义头、非简单方法如 POST），浏览器会先发送一个 OPTIONS 方法的预检请求。您的函数必须响应这个请求，并包含适当的 CORS 头。
- 在实际响应中包含 CORS 头：无论是成功响应还是错误响应，都应包含 Access-Control-Allow-Origin 等 CORS 头。
以下是一个配置 CORS 的 Edge Function 示例：
import { serve } from "server";
import * as cryptojs from "crypto-js"; // 示例中可能用到的库
import { config } from "dotenv"; // 示例中可能用到的库
// 加载环境变量 (如果需要)
await config();
// 定义 CORS 头部
const corsHeaders = {
'Access-Control-Allow-Origin': '*', // 允许所有来源访问，生产环境中建议指定具体域名
'Access-Control-Allow-Headers': 'authorization, x-client-info, apikey, content-type', // 允许的请求头
'Access-Control-Allow-Methods': 'POST, GET, OPTIONS', // 允许的 HTTP 方法
};
serve(async (req) => {
// 1. 处理 OPTIONS 预检请求
if (req.method === 'OPTIONS') {
return new Response('ok', { headers: corsHeaders });
}
try {
// 这里是您的 Edge Function 核心业务逻辑
// ...
// ...
const data = { message: "Function executed successfully!" }; // 示例数据
// 2. 在成功响应中包含 CORS 头部
return new Response(
JSON.stringify(data), {
status: 200,
headers: { ...corsHeaders, 'Content-Type': 'application/json' },
}
);
} catch (error) {
// 3. 在错误响应中也包含 CORS 头部
return new Response(
JSON.stringify({ error: error.message || error.toString() }), {
status: 500,
headers: { ...corsHeaders, 'Content-Type': 'application/json' },
}
);
}
});在上述代码中：
- Access-Control-Allow-Origin: '*' 允许任何来源的请求。在生产环境中，出于安全考虑，强烈建议将其替换为您的前端应用所在的具体域名，例如 https://your-app-domain.com。
- Access-Control-Allow-Headers 指定了客户端可以发送的自定义请求头。
- Access-Control-Allow-Methods 指定了允许的 HTTP 方法。
- req.method === 'OPTIONS' 用于捕获预检请求并直接返回一个带有 CORS 头的 ok 响应。
- 无论是成功还是失败的响应，都通过 { ...corsHeaders, 'Content-Type': 'application/json' } 确保 CORS 头被包含在内。
从浏览器调用 Edge Function
配置好 Edge Function 后，您可以使用 Supabase 客户端库从浏览器中调用它：
import { createClient } from '@supabase/supabase-js';
const supabase = createClient(
'YOUR_SUPABASE_URL',
'YOUR_SUPABASE_ANON_KEY'
);
async function callEdgeFunction(payment_link_id) {
try {
const response = await supabase.functions.invoke(
"retrieve-payment-link", {
body: {
id: payment_link_id,
},
// 如果需要，可以在这里添加额外的请求头
// headers: { 'Authorization': 'Bearer YOUR_AUTH_TOKEN' }
}
);
if (response.error) {
console.error('Edge Function invocation error:', response.error);
return null;
}
console.log('Edge Function response data:', response.data);
return response.data;
} catch (error) {
console.error('Network or unexpected error:', error);
return null;
}
}
// 示例调用
callEdgeFunction("some-payment-id");常见 CORS 错误排查与解决方案
当您在生产环境中遇到 CORS 错误，但本地测试却正常时，这通常表明本地环境与生产环境之间存在不一致。
1. 本地 Supabase Docker 环境未同步
这是导致本地与生产环境行为不一致的一个常见原因。Supabase CLI 及其关联的 Docker 容器可能会更新。如果您的本地 Docker 容器没有与最新的 CLI 版本同步，可能会导致在本地测试时无法复现生产环境中的问题，或者在本地表现正常的功能在生产环境却出现异常。
解决方案：
在 Supabase CLI 更新后，务必停止并重新启动您的本地 Supabase Docker 容器，以确保它们是最新的版本：
supabase stop supabase start
执行 supabase stop 会关闭所有正在运行的 Supabase Docker 容器，而 supabase start 会重新下载并启动最新版本的容器。这可以解决因本地环境过时而引起的各种部署和运行时问题，包括 CORS 行为的差异。
2. Access-Control-Allow-Origin 配置不当
- 生产环境安全性：虽然 * 在开发阶段很方便，但在生产环境中应将其替换为您的前端应用的精确域名（例如 https://your-app.com），以增强安全性。
- 多个来源：如果您需要支持多个来源，可以在服务器端动态检查 Origin 请求头，并将其回显为 Access-Control-Allow-Origin。
3. 缺少 Access-Control-Allow-Headers 或 Access-Control-Allow-Methods
如果您的请求使用了自定义请求头（如 Authorization）或非简单的 HTTP 方法（如 PUT, DELETE），但 Access-Control-Allow-Headers 或 Access-Control-Allow-Methods 未包含这些值，浏览器将阻止请求。确保您的 Edge Function 响应中包含了所有必要的头和方法。
4. Edge Function 未正确部署
每次修改 Edge Function 代码后，请确保使用正确的命令重新部署：
npx supabase functions deploy your-function-name --import-map supabase/functions/import_map.json
替换 your-function-name 为您的函数名称。
注意事项与最佳实践
- 安全性考虑：对于 Access-Control-Allow-Origin，避免在生产环境中使用 *。明确指定允许的源可以有效防止潜在的安全漏洞。
- 详细日志：在 Edge Function 中添加详细的日志记录，可以帮助您在生产环境中调试问题。Supabase 提供了 Edge Function 的日志查看功能。
- 浏览器开发者工具：始终利用浏览器的开发者工具（通常是 F12 键）来检查网络请求。在控制台和网络标签页中，您可以看到详细的 CORS 错误信息、请求和响应头部，这对于诊断问题至关重要。
- 测试环境：在将代码部署到生产环境之前，尽量在与生产环境尽可能相似的预发布或测试环境中进行全面的 CORS 测试。
总结
解决 Supabase Edge Function 中的 CORS 错误需要仔细配置 CORS 头部，并确保正确处理预检请求。当本地与生产环境行为不一致时，一个常见的但容易被忽视的原因是本地 Supabase Docker 容器与 CLI 版本不同步。通过遵循本文提供的配置指南和故障排除步骤，您可以有效地识别并解决 Edge Function 中的 CORS 问题，确保您的应用能够顺利地与后端函数进行交互。
