netlify-functions
编写 Netlify Serverless 函数的指南。在创建 API 端点、后台处理、计划任务,或任何使用 Netlify Functions 的服务端逻辑时使用。涵盖现代语法(默认导出 + Config)、TypeScript、路径路由、后台函数、计划函数、流式传输和方法路由。
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-08
- Stars
- ★ 37
- Forks
- 1
01 前言 Front Matter
- name
- netlify-functions
- description
- 编写 Netlify Serverless 函数的指南。在创建 API 端点、后台处理、计划任务,或任何使用 Netlify Functions 的服务端逻辑时使用。涵盖现代语法(默认导出 + Config)、TypeScript、路径路由、后台函数、计划函数、流式传输和方法路由。
02 资源文件 4
- 参考文档agents/openai.yaml358 B
- 资产文件assets/netlify-small.svg1.3 KB
- 资产文件assets/netlify.png2.6 KB
- 许可证LICENSE.txt10.7 KB
03 SKILL.md 正文
Netlify Functions
Modern Syntax
Always use the modern default export + Config pattern. Never use the legacy exports.handler or named handler export.
import type { Context, Config } from "@netlify/functions";
export default async (req: Request, context: Context) => {
return new Response("Hello, world!");
};
export const config: Config = {
path: "/api/hello",
};
The handler receives a standard Web API Request and returns a Response. The second argument is a Netlify Context object.
File Structure
Place functions in netlify/functions/:
netlify/functions/
_shared/ # Non-function shared code (underscore prefix)
auth.ts
db.ts
items.ts # -> /.netlify/functions/items (or custom path via config)
users/index.ts # -> /.netlify/functions/users
Use .ts or .mts extensions. If both .ts and .js exist with the same name, the .js file takes precedence.
Path Routing
Define custom paths via the config export:
export const config: Config = {
path: "/api/items", // Static path
// path: "/api/items/:id", // Path parameter
// path: ["/api/items", "/api/items/:id"], // Multiple paths
// excludedPath: "/api/items/special", // Excluded paths
// preferStatic: true, // Don't override static files
};
Without a path config, functions are available at /.netlify/functions/{name}. Setting a path makes the function available only at that path.
Access path parameters via context.params:
// config: { path: "/api/items/:id" }
export default async (req: Request, context: Context) => {
const { id } = context.params;
// ...
};
Method Routing
export default async (req: Request, context: Context) => {
switch (req.method) {
case "GET": return handleGet(context.params.id);
case "POST": return handlePost(await req.json());
case "DELETE": return handleDelete(context.params.id);
default: return new Response("Method not allowed", { status: 405 });
}
};
export const config: Config = {
path: "/api/items/:id",
method: ["GET", "POST", "DELETE"],
};
Background Functions
For long-running tasks (up to 15 minutes). The client receives an immediate 202 response; return values are ignored.
Name the file with a -background suffix:
netlify/functions/process-background.ts
Store results externally (Netlify Blobs, database) for later retrieval.
Scheduled Functions
Run on a cron schedule (UTC timezone):
export default async (req: Request) => {
const { next_run } = await req.json();
console.log("Next invocation at:", next_run);
};
export const config: Config = {
schedule: "@hourly", // or cron: "0 * * * *"
};
Shortcuts: @yearly, @monthly, @weekly, @daily, @hourly. Scheduled functions have a 30-second timeout and only run on published deploys.
Streaming Responses
Return a ReadableStream body for streamed responses (up to 20 MB):
export default async (req: Request) => {
const stream = new ReadableStream({ /* ... */ });
return new Response(stream, {
headers: { "Content-Type": "text/event-stream" },
});
};
Context Object
| Property | Description |
|---|---|
context.params |
Path parameters from config |
context.geo |
{ city, country: {code, name}, latitude, longitude, subdivision, timezone, postalCode } |
context.ip |
Client IP address |
context.cookies |
.get(), .set(), .delete() |
context.deploy |
{ context, id, published } |
context.site |
{ id, name, url } |
context.account.id |
Team account ID |
context.requestId |
Unique request ID |
context.waitUntil(promise) |
Extend execution after response is sent |
Environment Variables
Use Netlify.env (not process.env) inside functions:
const apiKey = Netlify.env.get("API_KEY");
Resource Limits
| Resource | Limit |
|---|---|
| Synchronous timeout | 60 seconds |
| Background timeout | 15 minutes |
| Scheduled timeout | 30 seconds |
| Memory | 1024 MB |
| Buffered payload | 6 MB |
| Streamed payload | 20 MB |
Framework Considerations
Frameworks with server-side capabilities (Astro, Next.js, Nuxt, SvelteKit, TanStack Start) typically generate their own serverless functions via adapters. You usually do not write raw Netlify Functions in these projects — the framework adapter handles server-side rendering and API routes. Write Netlify Functions directly when:
- Using a client-side-only framework (Vite + React SPA, vanilla JS)
- Adding background or scheduled tasks to any project
- Building standalone API endpoints outside the framework's routing
See the netlify-frameworks skill for adapter setup.
04 同仓库更多 Skills
android-emulator-qa
Use when validating Android feature flows in an emulator with adb-driven launch, input, UI-tree inspection, screenshots, and logcat capture.
supabase-postgres-best-practices
Postgres performance optimization and best practices from Supabase. Use this skill when writing, reviewing, or optimizing Postgres queries, schema designs, or database configurations.
sentry
Use when the user asks to inspect Sentry issues or events, summarize recent production errors, or pull basic Sentry health data via the Sentry API; perform read-only queries with the bundled script and require `SENTRY_AUTH_TOKEN`.
render-workflows
搭建、开发、测试和部署 Render Workflows。涵盖首次脚手架搭建(通过 CLI 或手动方式)、SDK 安装(Python 或 TypeScript)、任务模式(重试、子任务、扇出)、本地开发、控制台部署和故障排查。适用于用户首次搭建 Render Workflows、构建工作流服务、添加或修改工作流任务、本地测试工作流或部署到 Render 的场景。
render-web-services
配置 Render web service——端口绑定、TLS、健康检查、自定义域名、自动部署、PR 预览、持久化磁盘及部署生命周期。当用户需要搭建 web service、修复健康检查失败、添加自定义域名、配置零停机部署,或排查端口绑定问题时使用。
render-static-sites
在 Render 全球 CDN 上部署并配置静态站点——构建命令、发布路径、SPA 路由、重定向、自定义 header 及 PR 预览。当用户需要部署静态站点、搭建 React/Vue/Hugo/Gatsby 前端、配置 SPA 回退路由、添加重定向规则、自定义响应 header,或在静态站点与 web service 之间为前端做选择时使用。触发词:static site、CDN、SPA、single-page app、React deploy、Vue deploy、Hugo、Gatsby、Docusaurus、Jekyll、staticPublishPath。