函数

函数为什么存在

客户端 SDK 里的一切——from('table').select()、认证、存储——都用公开的 anon key（匿名密钥）对一层轻量网关发起调用，由行级安全负责守门。这覆盖了一个应用的大部分。但有些逻辑必须活在用户看不到、也改不了的地方：

• 密钥不能进打包产物。你的 Stripe secret key、厂商 API key、短信认证令牌——这些放进后端的密钥保险库，只能在服务端、在函数里读取。
• 受信任的逻辑不能跑在客户端。任何「让用户来决定答案」会出问题的事——创建 Checkout Session、校验优惠券、调用合作方 API——都应该放在服务端。
• 浏览器够不到某些主机。CORS、凭证和签名让很多厂商调用从页面上发起变得不可能（或不安全）。函数替你去发这个请求。

你通过slug——一个短名字——来访问函数。拿到 slug 有两条路：用内置函数（已经上线，只需设置好它的密钥），或者写一个自定义函数（你自己的 TypeScript）。两者的调用方式完全相同。

如何调用（两类通用）

在 SDK 里，用 slug 和一个可选的 body 调用 functions.invoke。和每个 SDK 调用一样，它返回一个 Result——{ data, error }——所以你永远不必把它包进 try/catch：

const { data, error } = await lingcode.functions.invoke('echo', {
  hello: 'world'
});
// data -> { hello: 'world', timestamp: '2026-06-11T…' }

或者通过 REST 调用——从服务器、curl 烟雾测试或非 JS 客户端发起时很方便。向函数端点 POST 一个 { input } body，由 anon key 或已登录用户的令牌授权：

POST https://lingcode.dev/api/cloud/be/<backend-id>/functions/<slug>
Authorization: Bearer <anon-key-or-user-token>
Content-Type: application/json

{ "input": { "hello": "world" } }

七个内置函数

这些在每个后端上都已上线，没有部署步骤。对每一个，你只需在密钥保险库里设置它所需的密钥（如果有），然后按 slug 调用。先从 echo 开始，确认你的接线没问题。

Slug	作用	输入	所需密钥
echo	原样返回你的输入，外加一个时间戳。用它来烟雾测试 invoke 是否正常。	任意内容	无
send-email	通过 LingCode 的托管发件方发送邮件。	{ to, subject, html }	无
elevenlabs-tts	文本转语音。返回 base64 音频。	{ text, voice_id?, model_id? } → { audio_base64, content_type }	ELEVENLABS_API_KEY
twilio-sms	通过 Twilio 发送短信。	{ to, body, from?, messaging_service_sid? }	TWILIO_ACCOUNT_SID、TWILIO_AUTH_TOKEN，外加 TWILIO_FROM 或 TWILIO_MESSAGING_SERVICE_SID 二者之一
resend-byo	通过你自己的 Resend 账户发送邮件。	{ from, to, subject, html?, text? }	RESEND_API_KEY
stripe-checkout	创建一个 Stripe Checkout Session。	{ price_id, success_url, cancel_url, mode?, quantity?, customer_email?, metadata? } → { id, url }	STRIPE_SECRET_KEY
http-fetch	向白名单内的主机发起一次出站 HTTPS 请求。	{ url, method?, headers?, body? }	自身无需密钥——但 header/body 字符串可以用 {{SECRET_NAME}} 引用保险库里的密钥

用 echo 做烟雾测试

新后端上最该先跑的东西。如果它把你的输入原样返回，说明 invoke 已接通，你的 URL + key 也都正确。

const { data } = await lingcode.functions.invoke('echo', { ping: 1 });
console.log(data); // { ping: 1, timestamp: '2026-06-11T…' }

创建一个 Stripe Checkout Session

先在密钥保险库里设置 STRIPE_SECRET_KEY——它永远不会碰到浏览器。然后调用这个内置函数，把用户重定向到返回的 URL：

const { data, error } = await lingcode.functions.invoke('stripe-checkout', {
  price_id:    'price_123',
  success_url: 'https://yourapp.com/thanks',
  cancel_url:  'https://yourapp.com/pricing',
  mode:        'subscription'
});
if (error) throw error;
window.location.href = data.url; // 托管的 Stripe Checkout

自定义函数

当没有内置函数合适时，就写你自己的。你在 Cloud 控制台 / IDE 里编写自定义函数——给函数一个 slug 和它的 TypeScript 源码（这是控制台里的一步编写动作，不是 agent 工具替你完成的事）。它们在 Deno 沙箱运行时里运行，用和内置函数同一个 functions.invoke(slug, body?) 调用来触发。

约定

你的源码必须 export default 一个 handler。你 return 的东西就成为调用结果的 data。原生支持 TypeScript——Deno 直接运行，无需构建步骤：

export default async function handler(input, ctx) {
  // ctx.secrets.MY_KEY  — 你的保险库密钥，仅服务端可见
  // ctx.backendId       — 这个后端的 id
  // ctx.gateway         — 这个后端自己的 data-API 基础 URL
  return { ok: true };   // 成为调用结果的 `data`
}

第二个参数 ctx 是你的服务端上下文：

ctx = {
  secrets:   { /* 保险库里设置的每一个密钥，按名字 */ },
  backendId: string,
  gateway:   string   // 通过它调用你自己的 data API
}

一个小小的自定义函数

从保险库读取一个密钥并返回 JSON。密钥从不离开服务端：

export default async function handler(input, ctx) {
  const key = ctx.secrets.WEATHER_API_KEY;
  const city = input.city ?? 'NYC';
  const res = await fetch(
    `https://api.example.com/weather?city=${city}&key=${key}`
  );
  const json = await res.json();
  return { city, tempC: json.temp_c };
}

从客户端调用它，和内置函数完全一样——按它的 slug：

const { data, error } = await lingcode.functions.invoke('get-weather', {
  city: 'Tokyo'
});
if (error) throw error;
console.log(data.tempC);

沙箱

自定义函数在 Deno 里运行，权限默认全部拒绝。这是一个特性，不是要去对抗的限制：

• 没有文件系统、没有环境变量、没有子进程、没有 FFI。函数读不了磁盘、起不了进程，也加载不了原生代码。
• 它能触达的唯一网络是后端自己的网关（ctx.gateway）。函数可以调用你的 data API——但它没法把数据外泄到任意主机。（需要触达某个厂商？用 http-fetch 内置函数的白名单，或者让你的函数绕回网关来发起。）
• 内存上限为 128 MB。

限制

限制	free	pro	max_pro
超时（墙钟时间，超过即 SIGKILL）	3s	10s	30s
自定义函数数量（maxFunctions）	2	10	50
源码体积	最多 256 KB
内存	128 MB

函数是短命的。超过墙钟超时后，进程会被 SIGKILL——没有优雅的延长机制。不要把任何运行超过约 30 秒的东西放进函数。

可用性

自定义函数需要 Deno 运行时，而它已经在生产环境安装并上线——自定义函数现在就能用。如果某次部署确实缺少运行时，自定义调用会返回 503 functions_runtime_unavailable，而内置函数照常工作（它们不依赖 Deno 沙箱）。所以自定义函数上的 503 是一个运行时可用性信号；内置函数失败则是另一回事。还要记住——unknown_function 永远是 slug 写错的错误，从不表示可用性问题。