AGENT SKILL

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

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

kael-odin
kael-odin/codex-plugins-zh

android-emulator-qa

Use when validating Android feature flows in an emulator with adb-driven launch, input, UI-tree inspection, screenshots, and logcat capture.

★ 37
kael-odin
kael-odin/codex-plugins-zh

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.

★ 37
kael-odin
kael-odin/codex-plugins-zh

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`.

★ 37
kael-odin
kael-odin/codex-plugins-zh

render-workflows

搭建、开发、测试和部署 Render Workflows。涵盖首次脚手架搭建(通过 CLI 或手动方式)、SDK 安装(Python 或 TypeScript)、任务模式(重试、子任务、扇出)、本地开发、控制台部署和故障排查。适用于用户首次搭建 Render Workflows、构建工作流服务、添加或修改工作流任务、本地测试工作流或部署到 Render 的场景。

★ 37
kael-odin
kael-odin/codex-plugins-zh

render-web-services

配置 Render web service——端口绑定、TLS、健康检查、自定义域名、自动部署、PR 预览、持久化磁盘及部署生命周期。当用户需要搭建 web service、修复健康检查失败、添加自定义域名、配置零停机部署,或排查端口绑定问题时使用。

★ 37
kael-odin
kael-odin/codex-plugins-zh

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。

★ 37