netlify-functions

Netlify Functions

最新のデフォルトハンドラー API（.mts TypeScript）を使用してください。Web の Request と Netlify の Context を受け取るデフォルトの非同期ハンドラーをエクスポートし、Web の Response を返します。Go を使用する場合や古いコードを移行する場合を除き、従来の AWS Lambda ハンドラー形式は避けてください（末尾の「レガシー」を参照）。

ファイルの配置場所

• デフォルトのディレクトリ：netlify/functions/（ベースディレクトリからの相対パス）。公開ディレクトリの外側に配置してください。そうしないと、ソースファイルが静的アセットとして配信されます。
• 関数は、1つのファイル、またはエントリーファイルの名前が index かサブディレクトリ名と一致するサブディレクトリです。以下はいずれも hello 関数を作成します。
  • netlify/functions/hello.mts
  • netlify/functions/hello/hello.mts
  • netlify/functions/hello/index.mts
• ES モジュールには .mts（TS）／.mjs（JS）を使用してください。.cts／.cjs は CommonJS を強制し、.ts／.js は最も近い package.json の "type" に従います。

⚠️ 同じ名前の JS ファイルと TS ファイルがある場合、JS ファイルが優先されます。 関数ディレクトリに items.js と items.ts などがある場合、JavaScript 関数がデプロイされ、TypeScript ファイルは警告なしで無視されます。.ts を編集しても反映されません。関数名ごとにファイルを1つだけ残し、関数を TypeScript に移行する際は古い .js ファイルを削除するか、名前を変更してください。

最小限の関数

config のエクスポートは不要です。/.netlify/functions/hello でアクセスできます。

import type { Context } from "@netlify/functions"

export default async (req: Request, context: Context) => {
  return new Response("Hello, world!")
}

型をインストールします：npm install @netlify/functions（TS の型には必須、JS では任意）。

環境変数とシークレットは Netlify.env.get() で読み取ります。

const apiKey = Netlify.env.get("STRIPE_SECRET_KEY")

シークレットをハードコードしないでください。変数を実行時に使用できるようにするには、そのスコープに Functions が含まれている必要があります。netlify.toml で設定した変数は、関数からは利用できません。値はデプロイごとに固定されます。変更を反映するには、再デプロイしてください。

レスポンスヘッダーは、返される Response にコード内で設定します。 netlify.toml の [[headers]]、_headers、リダイレクトのヘッダールールは、静的 CDN レスポンスにのみ適用され、関数のレスポンスには適用されません。明示的に要求されていない限り、CORS ヘッダーを追加しないでください。

カスタムパスのルーティング

config.path を設定すると、カスタム URL にルーティングできます。設定した場合、関数はそのパスでのみアクセスでき、/.netlify/functions/<name> ではアクセスできません。

import type { Config, Context } from "@netlify/functions"

export default async (req: Request, context: Context) => {
  const { city, country } = context.params
  return new Response(`You're visiting ${city} in ${country}!`)
}

export const config: Config = {
  path: "/travel-guide/:city/:country",
}

• 複数のパス：path: ["/cats", "/dogs"]。
• パターン：path は URLPattern の構文に対応しています。例：path: ["/sale/*", "/item/:sku"]。名前付きグループは context.params に格納されます。クエリ文字列には req.url を使用してください。
• excludedPath：例外を指定します。たとえば、path: "/product/*" に対して excludedPath: ["/product/*.css"] を指定します。
• preferStatic: true：URL に実在する静的ファイルがある場合、そちらを優先します。
• method：メソッドを制限します。例：method: ["GET", "POST"]。

Fetchable モジュールの形式（別の方法）

基本のハンドラーと同等です。config をインラインで含み、イベントハンドラーを追加できます。

import type { NetlifyFunction } from "@netlify/functions"

export default {
  fetch: (req, context) => new Response("Hello, world!"),
  config: { path: "/hello" },
} satisfies NetlifyFunction

Context オブジェクト

ハンドラーの第2引数です（ハンドラーのスコープ外では @netlify/functions の getContext() を使用できます。リクエスト外で呼び出すと例外が発生するため、try/catch で囲んでください）。

• context.params — 名前付きパスパラメーター。
• context.geo — city、country.code/name、latitude、longitude、subdivision、timezone、postalCode。
• context.ip — クライアントの IP 文字列。
• context.cookies — get(name)／set(options)／delete(name|options)。サブドメイン間で Cookie を共有するには、カスタムドメインが必要です（netlify.app は Public Suffix List に登録されています）。
• context.site — id、name、url。context.deploy — context、id、published、skewProtectionToken。context.account.id。context.server.region。context.requestId。
• context.user — プライベートプロジェクト、またはチームログインで保護されたプロジェクトにログインした Netlify ユーザー：id、email（undefined の場合があります）、expiresAt（Date）。以下を参照してください。
• context.waitUntil(promise) — レスポンスの送信後に、レスポンスをブロックせずに処理（分析、ログ記録）を実行します。課金とログの処理時間は、promise が解決するまでカウントされます。2025-03-20 以降にデプロイされた関数で利用できます。

⚠️ netlify dev では context.geo／context.ip はモックされます。netlify dev --geo=mock --country=DE を使ってテストしてください。

呼び出し元：context.user

⚠️ context.user は undefined になることがよくあります。公開プロジェクト、基本的なパスワード保護、ローカルの netlify dev、2026 年 10 月 5 日より前にデプロイされた関数（有効にするには再デプロイしてください）が該当します。必ずこの状態を処理し、レコードのキーには id を使用してください（email が undefined の場合があります）。

import type { Config, Context } from "@netlify/functions"

export default async (req: Request, context: Context) => {
  if (!context.user) {
    // Public project, basic password protection, local CLI, or pre-2026-10-05 deploy.
    return Response.json({ user: null }, { status: 401 })
  }
  return Response.json({
    id: context.user.id,
    email: context.user.email ?? null,
    expiresAt: context.user.expiresAt.toISOString(),
  })
}

export const config: Config = { path: "/whoami" }

Config オブジェクト

const config（または Fetchable モジュールの config プロパティ）をエクスポートします。

• path / excludedPath — string | string[]。/ で始まる必要があります。
• method — 1 つのメソッドまたは配列。
• preferStatic — boolean。
• background — boolean（「バックグラウンド」を参照）。
• schedule — cron 文字列（「スケジュール実行」を参照）。path / excludedPath とは併用できません。
• rateLimit — { action: 'rate_limit'|'rewrite', aggregateBy: 'domain'|'ip'|[...], to?, windowSize, windowLimit }。
• memory / vcpu — 以下を参照。相互に併用できません。
• region — 空港コード。以下を参照。

インテグレーション

import type { Config } from "@netlify/functions"
import { getDatabase } from "@netlify/database"

const db = getDatabase()

export default async (req: Request) => {
  const users = await db.sql`SELECT id, email FROM users LIMIT 10`
  return Response.json({ users })
}

export const config: Config = { path: "/users" }

Blobs：import { getStore } from "@netlify/blobs"；getStore("uploads").set(key, await req.blob())。

キャッシュ：@netlify/functions の await purgeCache({ tags: ["products"] }) はエッジキャッシュを無効化します（すべてを削除するには tags を省略します）。

ストリーミングレスポンス

Response の本文として ReadableStream を返します。制限：実行時間 60 秒、レスポンス 20 MB。

export default async (req: Request) => {
  const res = await fetch("https://api.openai.com/v1/chat/completions", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${Netlify.env.get("OPENAI_API_KEY")}`,
    },
    body: JSON.stringify({ model: "gpt-4o-mini", stream: true, messages: [/* ... */] }),
  })
  return new Response(res.body, { headers: { "content-type": "text/event-stream" } })
}

バックグラウンド関数（長時間実行）

config.background: true を設定します。クライアントには即座に 202 が返され、戻り値は破棄されます。最大 15 分間実行されます。ストリーミングには対応していません。再試行：呼び出しエラーが発生すると、1 分後に再試行し、その 2 分後にもう一度再試行します。結果はクライアント以外の場所に送信してください。

import type { Config } from "@netlify/functions"

export default async (req: Request) => {
  // Long-running work. Client already has its 202.
}

export const config: Config = { background: true, path: "/process" }

制限：バックグラウンドのペイロードは 256 KB です。従来の -background ファイル名サフィックスも引き続き機能しますが、config.background の使用を推奨します。

スケジュール実行関数（cron）

cron 式を指定した config.schedule を使います。UTC で実行されます。リクエスト本文は next_run（ISO-8601）を含む JSON です。インライン設定は TS/JS のみ対応しています。Go では netlify.toml を使用する必要があります。

対象となる現地時刻に対応する UTC 時刻を必ず計算してください。例：ET の午前 9 時 → UTC では "0 13 * * *"（DST の切り替わりで 1 時間ずれる点に注意し、必要な UTC オフセットを選んでください）。特定の現地時刻を指定できない @daily / @hourly の省略形より、明示的な cron 式を推奨します。

import type { Config } from "@netlify/functions"

export default async (req: Request) => {
  const { next_run } = await req.json()
  console.log("Next invocation at:", next_run)
}

export const config: Config = {
  schedule: "0 13 * * *", // 9 AM ET (EST); UTC
}

netlify.toml を使用する場合（すべての言語に対応）：

[functions."daily-digest"]
  schedule = "0 13 * * *"

制約：30 秒の制限（それ以上かかる場合はバックグラウンドを使用）。公開済みデプロイでのみ実行されます（Deploy Previews / ブランチデプロイでは実行されません。Run now で手動実行してください）。URL からの呼び出しには対応していません。ストリーミング、リクエストペイロード / POST データには対応していません。Split Testing とは併用できません。@reboot と @annually 以外のすべての拡張表記に対応しています。

プラットフォームイベント関数

イベント名をハンドラー名とするデフォルトオブジェクトをエクスポートします。常にバックグラウンドで実行され、クライアントへのレスポンスはありません。同じ関数内で fetch と組み合わせられます。各ハンドラーは完全に型付けされています。イベント型は @netlify/functions からインポートしてください。

import type { DeploySucceededEvent, DeployFailedEvent } from "@netlify/functions"

export default {
  deploySucceeded(event: DeploySucceededEvent) {
    console.log(`Deploy ${event.deploy.id} succeeded for ${event.site.name}`)
  },
  deployFailed(event: DeployFailedEvent) {
    console.log(`Deploy ${event.deploy.id} failed: ${event.deploy.errorMessage}`)
  },
}

デプロイイベント（event.deploy、event.site。戻り値は void）：deployBuilding、deploySucceeded、deployFailed、deployDeleted、deployLocked、deployUnlocked。

Identity イベント（event.user。保証されるのは id のみ）：

ハンドラー	拒否可能	変更可能
userValidate	はい	はい
userSignup	はい	はい
userLogin	はい	はい
userModified	はい	はい
userDeleted	いいえ	いいえ

• 拒否：ハンドラー内で event.deny() を呼び出すと、エンドユーザーには 401 が返されます。最初に拒否した関数の時点でチェーンは中断されます。
• 変更：{ user: {...} } を返すと変更が保存されます。undefined を返すと、そのまま次に引き渡されます。

フォームイベント：formSubmitted → event.data（フィールド名をキーとするオブジェクト）。戻り値は void です。

複数の関数で同じイベントを処理できます（すべて実行されます）。Netlify は各イベントに署名（JWS）を付与し、呼び出し前に検証して、外部リクエストをブロックします。従来のファイル名規則（イベント名のファイルで、await req.json() → payload からペイロードを取得）も引き続き機能しますが、型付きハンドラーの使用を推奨します。

リージョン

⚠️ 明確な理由がない限り、config.region を上書きしないでください。cmh（米国東部、オハイオ州）のデフォルトは意図的に設定されています。

正当な理由がある場合（例：EU 内にあるデータベース）：

export const config: Config = { path: "/eu-data", region: "dub" }

空港コード（セルフサービス）：cmh、dub、fra、gru、iad、lhr、nrt、pdx、sfo、sin、syd、yul。サポート対応：cdg、mxp。各関数は必ず1つのリージョンで実行されます（マルチリージョンのジオルーティングには対応していません）。リージョンの選択には Pro／Enterprise が必要です。フレームワークアダプターが生成する関数では export const config を指定できません。UI のプロジェクトレベルの Cloud compute > Functions > Region でリージョンを設定してください。リージョンを変更した後は、再デプロイしてください。関数レベルのリージョン設定は、サイトレベルの UI 設定より優先されます。

メモリ／vCPU

⚠️ 憶測で config.memory や config.vcpu を設定しないでください。料金はサイズに比例して増加します。

正当な理由がある場合（例：大きな PDF の処理で OOM が発生したことを確認した場合）：

export const config: Config = { path: "/heavy", memory: "2gb" } // or memory: 2048

• memory：1024～4096 MB。vcpu：0.5～2.0（0.5 → 1024 MB、2.0 → 4096 MB）。これらは相互排他的です。Netlify がもう一方のサイズを自動設定します。Credit ベースの Pro／Enterprise が必要です。netlify.toml で設定する場合：[functions.heavy]\n memory = "2gb"。

バンドルとディスク上のファイル

⚠️ 実行時に fs.readFile で読み込むファイルはバンドルされません（本番環境では ENOENT が発生します）。静的データはモジュールとしてインポートするか、次のように宣言してください。

[functions]
  included_files = ["files/*.md"]
  external_node_modules = ["package-1"]

⚠️ すべての関数を合計した環境変数の上限は 約 4 KB です。PEM キーやサービスアカウントの JSON は環境変数に含めないでください。

JS のみの esbuild：[functions]\n node_bundler = "esbuild"。

制限（設定不可）

• 同期実行：60s。スケジュール実行：30s。バックグラウンド実行：15 min。
• バッファリングされるリクエスト／レスポンスのペイロード：6 MB（バイナリは Base64 エンコードされるため、オーバーヘッドは約 30% となり、実質的なバイナリの上限は 4.5 MBです）。
• ストリーミングレスポンス：20 MB。バックグラウンドペイロード：256 KB。

ローカルでのテストとデプロイ

• ほとんどのフレームワークでは、開発サーバーで関数をエミュレートできます。Vite フレームワーク（Astro、Nuxt、TanStack Start、React Router）では、@netlify/vite-plugin をインストールして開発サーバーを実行してください。Next.js などそれ以外の場合は、Netlify CLI（netlify dev）を使用してください。
• スケジュール関数はローカルではスケジュールどおりに実行されません。netlify functions:invoke <name> で1回実行してください。
• デプロイ：継続的デプロイには Git にプッシュするか、Netlify CLI／API を使用してください。
• ログとメトリクスは Netlify UI に表示されます。CLI でストリーミングできます。デプロイ済みの関数バージョンはすべて Functions タブに表示されます。リスト上部の検索フィールドで関数名を絞り込み、別のフィルターでブランチを選択するか、Deploy Preview 番号を入力してください。

Node ランタイムのバージョン

ランタイムにはビルドで使用された Node.js のバージョンが適用されます（フォールバック：Node.js 24）。上書きするには、UI／CLI／API から環境変数 AWS_LAMBDA_JS_RUNTIME（例：nodejs24.x）を設定し、再デプロイしてください。netlify.toml では設定できません。ES モジュールでは __dirname／__filename は使用できません。import.meta.url を使用してください。CommonJS パッケージの名前付きインポートは失敗するため、デフォルトインポートを使用してください。

レガシー／Go（必要な場合を除き使用しないでください）

Go では Lambda 互換 API を使用する必要があります。Go のルーティング／リージョン／メモリは netlify.toml で設定します。Lambda 形式の JS／TS を移行する場合、@netlify/aws-lambda-compat で AWS ハンドラーをラップできます。

import { withLambda } from "@netlify/aws-lambda-compat"
import type { HandlerContext, HandlerEvent, HandlerResponse } from "@netlify/aws-lambda-compat"

export default withLambda(async (event: HandlerEvent, context: HandlerContext): Promise<HandlerResponse> => {
  const name = event.queryStringParameters?.name ?? "World"
  return { statusCode: 200, headers: { "content-type": "application/json" }, body: JSON.stringify({ name }) }
})

Netlify の関数に関するルール

これらは組織内の規約であり、ドキュメントの事実ではありません。ctx-gen によってレンダリングされるスキルに統合され、生成されることはありません。以前の手書きの netlify-functions スキルから抽出したもので、スキルのメンテナーが管理しています。

1. 可能な場合は TypeScript（.mts）を使用してください。
2. 環境変数には Netlify.env.get() を使用してください（一貫性を保つため、process.env よりこちらを推奨します）。
3. 明示的に求められない限り、CORS ヘッダーは追加しないでください。
4. シークレットはコードに記述せず、環境変数に保存してください。
5. context.geo と context.ip は netlify dev ではモックされており、プレースホルダー値が使われます。実際の場所やクライアント IP ではありません。ローカルの値が変わらないからといって、地理情報を扱うコードが壊れていると判断しないでください。netlify dev --geo=mock --country=DE で分岐をテストし、デプロイ後にも確認してください。
6. 推測で config.memory や config.vcpu を設定しないでください。メモリや計算負荷の高い処理だと分かっている場合、または関数自体の処理が原因で OOM やタイムアウトが発生したと確認できた場合にのみ、値を増やしてください。料金はサイズに比例して直線的に増加します。
7. ユーザーが具体的な理由（データベース／バックエンドとの同一リージョン配置、データレジデンシー、対象地域のユーザーなど）を示していない限り、config.region を上書きしないでください。デフォルトの cmh は意図的に選択されています。
8. 実行時にディスクから読み込むファイル（テンプレート、JSON、WASM に対する fs.readFile など）はバンドルされません。netlify dev では動作しても、本番環境では ENOENT になります。静的データはモジュールとしてインポートすることを優先してください。それ以外の場合は、netlify.toml に対象を限定した included_files エントリーを宣言してください。
9. 環境変数の合計約 4 KB の制限は、Lambda 互換モードだけでなく、すべての関数に適用されます（関数は AWS Lambda 上で実行されます）。大きなペイロード（サービスアカウントの JSON、PEM キーなど）は環境変数に格納せず、バンドルされたファイル、Blobs、または実行時のフェッチを使用してください。この上限を引き上げる Netlify の設定はありません。
10. 本文中の最初の関数の例は、必ず最小限のデフォルトにしてください。config のエクスポートは一切含めず、関数が /.netlify/functions/<name> で提供されることを明記してください。カスタムの path ルーティングは後の例でのみ示してください。エージェントは最初に目にした例を模倣します。
11. 汎用的な例では memory、vcpu、region を示さないでください。確認済みの OOM、バックエンドとの同一リージョン配置、データレジデンシーなど、明示した理由がある場合にのみ示してください。
12. スケジュール関数の例では、実際の cron 式を使用し、UTC への変換を明記してください（例：東部時間の午前 9 時 → UTC の "0 13 * * *"。夏時間についても注記してください）。特定の現地時刻を指定できない @hourly／@daily のような簡略表記だけを使わないでください。
13. 本文では、netlify.toml の [[headers]]、_headers、リダイレクトのヘッダールールは、静的 CDN レスポンスにのみ適用されることを明記してください。関数のレスポンスヘッダーは、返却する Response にコード内で設定します。
14. レポートの生成、アップロードの処理、ダイジェストの送信など、特定の処理を行う関数の作成を求められた場合は、その処理を実装してください。必要に応じて実際のライブラリを選び、処理を最初から最後まで記述してください。完成した配線の背後に not implemented のスタブを置き、中心となる分岐が例外を投げる関数を、設定やルーティングがどれほど整っていても、動作する回答として提示してはいけません。
15. 関数をバックグラウンド関数にする、現在サポートされている方法として文書化されているのは config.background: true です（ファイル名の接尾辞 -background も引き続き使用できます）。ローカルにインストールされたバンドラーがこのフラグを認識しない場合は、まずバージョンの不一致を疑ってください。ローカルのツールを確認してアップグレードし、ローカル互換性の調査結果とプラットフォームのサポートに関する説明は分けてください。古いインストール済みスキーマだけを根拠に、ドキュメントで推奨されているフラグを回答から削除してはいけません。
16. プライベートプロジェクト、またはチームログイン保護が有効なプロジェクトでは、context.user はリクエストを行った Netlify ユーザーを表します（id、email、expiresAt）。そのログインで保護されたアプリケーションで、呼び出し元のユーザーを把握する必要がある場合（個人別のデータ、監査ログ、承認、個人別の設定など）は、2つ目のログインを追加せず、context.user を読み取ってください。Netlify は関数の実行前にログインを検証するため、クライアントから送信されたヘッダーや Cookie からユーザー ID を取得してはいけません。すべての例で、context.user が undefined になる可能性に対処してください。該当するのは、公開プロジェクト、基本的なパスワード保護、netlify dev、およびサイトを再デプロイする前の 2026 年 10 月 5 日より前にデプロイされた関数です。email も undefined になる可能性があるため、保存するレコードのキーには id を使用してください。これは Netlify のアカウントであり、Netlify Identity のユーザーではありません。Netlify Identity の場合は、@netlify/identity の getUser() を使用してください。