🎉

Next.js Server Actionsの仕組みと実践的な使い方

に公開
2026/02/24

はじめまして、_minoです!

この記事では、Next.js Server Actionsの仕組みと実践的な使い方について深掘りしています。
Server Actionsについて詳しく知りたい方や実務で使っていきたい方の参考になれば幸いです。

🔥 Server Actions とは

Server Actions は、Next.js v13.4 で実験的機能として導入され、v14 で正式リリースされた機能です。<form /> の action 属性に渡すことで、サーバー側で実行される非同期関数を定義できます。
https://nextjs.org/docs/app/getting-started/updating-data

Server Actions の背景について、Vercel 公式ブログの「サーバーアクション:Reactにおける非同期処理の新たな取り組み」で言及されています。

Server Functions との関係

Next.js v15 以降では、新たに「Server Functions」という用語が追加され、従来の「Server Actions」と明確に区別されるようになりました。

公式でもこのように記載されています。

2024年9月まで、私たちはすべての Server Functions を「Server Actions」と呼んでいました。action プロパティに渡されるか、action 内から呼び出される Server Function は Server Action ですが、すべての Server Function が Server Action に該当するわけではありません。本ドキュメントの表記を更新し、Server Functions が複数の用途に使用可能であることを反映しました。

https://react.dev/reference/rsc/server-functions

つまり、現時点での位置づけは以下のようになっています。

  • Server Functions: 'use server' で定義されるサーバー側で実行される関数の総称
  • Server Actions: Server Functions のうち、<form action> に渡す、startTransition 内で呼び出すなど、アクションとして使用されるもの

「Server Functions」と「Server Actions」の違いについては、こちらの記事で丁寧にまとめられているので参考になります👇

https://zenn.dev/b13o/articles/actions-vs-serverfunctions

各プラットフォームの対応状況

主要なホスティングサービスでの Server Actions 対応状況です。基本的にどのプラットフォームでも利用可能です。

プラットフォーム 対応状況 ドキュメント
Vercel ✅ サポート Next.js公式
Netlify ✅ サポート Netlify公式
AWS Amplify Hosting ✅ サポート AWS公式
Cloudflare Workers ✅ サポート Cloudflare公式
Firebase App Hosting ✅ サポート Firebase公式
Node.js / Docker(EC2、Cloud Run など) ✅ サポート Next.js公式

🏖️ Route Handlers との違い

Route Handlers とは

Next.js では app ディレクトリ配下に route.ts(または route.js)ファイルを作成することで、Web API エンドポイントを構築できます。
GET、POST、PUT、PATCH、DELETE などの HTTP メソッドに対応しています。

https://nextjs.org/docs/app/getting-started/route-handlers

設計思想と特徴の比較

「Route Handlers」 と 「Server Actions」 は、どちらもサーバーサイドで実行されるコードをクライアントから呼び出す仕組みですが、設計思想や用途が異なります。

Route Handlers は従来の REST API と同じ考え方で、HTTP のリクエスト/レスポンスを直接扱います。柔軟性が高い反面、呼び出し側で fetch() を使う必要があり、型の管理も手動で行う必要があります。

一方、Server Actions はデータ更新に特化しており、通常の JavaScript 関数のように呼び出せます。fetch() を書く必要がなく、関数呼び出しの形式なので TypeScript との相性も良いため、よりシンプルに記述できます。

項目 Route Handlers Server Actions
定義場所 route.ts ファイル 'use server' ディレクティブ
HTTP メソッド GET, POST, PUT, DELETE など POST のみ
呼び出し方法 fetch() 経由 関数として直接呼び出し
型安全性 手動で型付けが必要 TypeScriptの型推論が効きやすい
キャッシュ GET はキャッシュ可能 キャッシュされない
外部からのアクセス 可能(Webhook など) 不可(アプリ内部のみ)
主な用途 データ取得、外部連携 データ更新

ユースケースごとの使い分け

使い分けに明確なルールはありませんが、一般的には以下のように分けるのが良いとされています。

Server Actions を使う場合

  • お問い合わせフォームやログインフォームの送信
  • 記事・コメントの投稿、編集、削除
  • いいねボタンやお気に入り登録などの UI 操作

Route Handlers を使う場合

  • Stripe や GitHub などからの Webhook 受信
  • 外部サービスやサードパーティ向けの API 提供
  • モバイルアプリや別ドメインのクライアントからのアクセス

こちらの記事が参考になります👇
https://zenn.dev/coconala/articles/82a805fa39e76b

📝 内部の仕組みを理解する

Server Actions が裏側でどのような挙動になっているかについて、以下の3つのフェーズに分けてポイントを抜粋して解説します。

  1. ビルド時
  2. クライアント実行時
  3. サーバー実行時

1. ビルド時

アクション ID の生成
ビルド時に Next.js は "use server" ディレクティブを検知し、各関数に対してユニークなアクションIDを生成します。

"use server";

async function actionFun(formData: FormData) {
  // ...
}

この関数に対して、以下のようなアクションIDが割り当てられます。

アクションID: "6a88c2d1e4f..."

クライアント用コードの生成
ビルド時に、Server Actionの関数本体はクライアントバンドルから除外され、代わりにアクションIDを使ってサーバーにリクエストを送るための「参照コード」だけが生成されます。

// クライアントバンドルに含まれるコード
import { createServerReference } from "react-server-dom-webpack/client";

// 関数の中身ではなく、サーバーへの参照のみ
export const actionFun = createServerReference("6a88c2d1e4f...");

createServerReference() は、アクションIDを受け取り、呼び出されるとそのIDをサーバーにPOSTリクエストとして送信する関数を返します。

📎 該当のソースコード: createServerReference()

これにより、サーバー側のロジックはクライアントに露出せず、必要最小限のコードだけが配信されます。

マニフェストファイルの生成
アクションIDと実際の関数のマッピング情報は、ビルド時にマニフェストファイル(.next/server/配下)として保存されます。

サーバーはリクエストを受け取ると、このファイルを参照してアクションIDに対応する関数を特定し、実行します。

{
  "node": {  
    "6a88c2d1e4f...": {
      "workers": {  
        "app/...": {
          "moduleId": "...",
          "async": false,
          "exportedName": "actionFun",
          "filename": "..."
        }
      },
      "layer": { 
        "app/...": "action-browser"
      },
      "filename": "...",
      "exportedName": "actionFun"
    }
  },
  "edge": {}, 
  "encryptionKey": "..." 
}
キー 説明
node Node.jsランタイムで実行されるアクション
edge Edgeランタイムで実行されるアクション
workers このアクションを使用しているページの一覧
layer 各ページでの実行コンテキスト
encryptionKey クロージャ変数の暗号化に使用するキー

2. クライアント実行時

<form />と useActionState を使用してフォームを実装する場合、HTML には以下のような <input type="hidden" ...> が自動生成されます。

ここにはアクション ID やバインドされた状態などの情報が格納されています。

<form action enctype="multipart/form-data" method="POST">
    <input type="hidden" name="$ACTION_REF_1">
    <input type="hidden" name="$ACTION_1:0" value="{"id":"600fbcb...","bound":"$@1"}">
    <input type="hidden" name="$ACTION_1:1" value="[{"success":false,"error":null,"message":null}]">
    <input type="hidden" name="$ACTION_KEY" value="k4e00a4ec...">
    ...
</form>

フォームを送信すると、内部では以下のような fetch 処理が裏側で実行されます。

async function fetchServerAction(state, nextUrl, { actionId, actionArgs }) {
  // 引数をシリアライズ
  const body = await encodeReply(actionArgs, { temporaryReferences });

  // ヘッダーを構築
  const headers = {
    Accept: RSC_CONTENT_TYPE_HEADER,              // 'text/x-component'
    [ACTION_HEADER]: actionId,                    // 'Next-Action'
    [NEXT_ROUTER_STATE_TREE_HEADER]: prepareFlightRouterStateForRequest(state.tree),
  };

  // サーバーに POST リクエストを送信
  const res = await fetch(state.canonicalUrl, { method: 'POST', headers, body });

  // リダイレクト処理、RSC レスポンス解析、エラーハンドリング...
}

📎 該当のソースコード: fetchServerAction()

サーバーに送信されるリクエストには以下の情報が含まれます。

項目 説明
メソッド 常に POST
URL 現在のページの URL(例: /todos)
Next-Action ヘッダー 実行するアクション ID(例:6a88c2d1e4f...)
Next-Router-State-Tree ヘッダー 現在のルーター状態(ナビゲーション用)
Accept ヘッダー RSC 形式を指定(text/x-component)
Body シリアライズされた引数(React Flight 形式)

3. サーバー実行時

クライアントから送られてきたリクエストを受け取り、アクションID をもとに対応する関数を特定・実行します。

async function handleAction(req, serverModuleMap) {
  // 1. Next-Action ヘッダーからアクション ID を取得
  const actionId = req.headers.get('Next-Action');

  // 2. リクエストボディから FormData を取得
  const formData = await req.formData();

  // 3. アクション ID に対応する関数を特定
  const action = await decodeAction(formData, serverModuleMap);
  if (!action) {
    throw new Error(
      `Failed to find Server Action "${actionId}". ` +
      `This request might be from an older or newer deployment.`
    );
  }

  // 4. 関数を実行
  const result = await action();

  // 5. 結果を RSC Payload 形式で返却
  return result;
}

📎 該当のソースコード: handleAction()

処理の流れをまとめると以下の通りです。

  1. Next-Action ヘッダーからアクションIDを取得
  2. serverModuleMap(マニフェスト)からIDに対応する関数を検索
  3. 引数をデシリアライズして関数を実行
  4. 結果を RSC Payload 形式でクライアントに返却

関数内で revalidatePath や redirect が呼ばれた場合、その情報もレスポンスに含まれ、クライアント側で適切に処理されます。

このように、開発者が直接 fetch を書く必要はなく、Server Actions を通常の関数として呼び出すだけで上記の処理が自動的に行われます。

📝 Server Actions 使用時の注意点

Server Actions は手軽にサーバー処理を実装できますが、その手軽さゆえに見落としがちな注意点があります。

セキュリティ観点

Server Actions には Next.js による組み込みの保護機能があります。

  • 同一オリジン制限: Origin ヘッダーと Host ヘッダーを比較し、異なる場合はリクエストを拒否。そのため、Server Actions はアプリケーション内からのみ呼び出し可能で、外部ドメインからの利用はできません。
  • CSRF対策: POSTメソッドのみ許可。また、ブラウザではSameSite Cookieがデフォルトのため、多くのCSRF攻撃を防止できる。
  • Secure Action IDs: 予測不可能な暗号化IDでエンドポイントを参照。セキュリティ強化のため、これらのIDはビルドごとに定期的に再計算されます。
  • Dead Code Elimination: 未使用の Server Actions はクライアントバンドルから削除。

これらの保護があっても、Server Actions は 「公開 HTTP エンドポイント」です。UI 上でボタンを非表示にしても API 自体は呼び出し可能であり、悪意のあるユーザーが直接 POST リクエストを送信できます。

公式でもこのように記載されています。

これらのIDはコンパイル時に生成され、最大14日間キャッシュされます。新規ビルドが開始されるか、またはビルドキャッシュが無効化された際に再生成されます。 このセキュリティ強化により、認証レイヤーが存在しない場合のリスクを軽減できます。 ただし、Server Actionは公開HTTPエンドポイントと同様に扱う必要があります。

https://nextjs.org/docs/app/guides/data-security#mutating-data

そのため、以下の対策は MUST で実装する必要があります。


1. 認証の必要性

ログインが必要な処理では、必ず Server Action 内で認証済みセッションを確認する。

この実装がない場合、未認証のユーザーが API を直接叩いてデータを操作できてしまうリスクがあります。

async function action(formData: FormData) {
  const session = await getSession(); // next-auth等の認証ライブラリを使用
  if (!session) {
    return { error: "認証が必要です", status: 401 };
  }
  // ...
}

2. バリデーションの必要性

Zod や Valibot などのスキーマバリデーションライブラリを使用して、Server Action 内で期待する型であるのかを必ず検証する。

この実装がない場合、予期しないデータ型や不正な値が DB に保存されたり、アプリケーションがクラッシュするリスクがあります。

async function action(formData: FormData) {
  const result = schema.safeParse({
    // ...
  });

  if (!result.success) {
    return { error: "入力内容が正しくありません", status: 400 };
  }
  // ...
}

3. エラーハンドリング

内部エラーはサーバーログに記録し、クライアントには「システムエラーが発生しました」などの汎用メッセージを返すようにする。

サーバーで発生したエラーをそのままクライアントに返すと、DB 接続情報やスタックトレースなどの機密情報が漏洩するリスクがあります。

async function action(formData: FormData) {
  try {
    // ...
  } catch (error) {
    // ❌ エラーをそのまま返すと機密情報が漏洩する
    return { error: error.message, status: 500 };

    // ✅ ログに記録し、汎用メッセージを返す
    console.error(error);
    return { error: "システムエラーが発生しました", status: 500 };
  }
}

4. 機密情報のクライアント公開を制御

Server Action 内で機密データを扱う場合は、React の taintUniqueValue 、taintObjectReference を使用して、誤ってクライアントに送信されることを防ぐことができます。どちらかというと開発者のミス防止で設定します。

https://nextjs.org/docs/app/api-reference/config/next-config-js/taint

執筆時点では実験的な機能ではありますが、以下のようにして制御することができます。

import { experimental_taintUniqueValue } from "react";

async function action(formData: FormData) {
  const [user] = await sql`SELECT * FROM users WHERE id = ${id}`;

  experimental_taintUniqueValue(
    "password_hashをクライアントに渡さないでください",
    user,
    user.password_hash
  );

  // ❌ password_hashを含めるとエラー
  return { data: user.password_hash, status: 200 };

  // ✅ 安全なフィールドのみ返す
  return { name: user.name, email: user.email, status: 200 };
}

5. キャッシュ再検証

Next.js の App Router でキャッシュ設定をしている場合、Server Action でデータを変更しても、キャッシュを再検証しないと古いデータが表示され続けます。

データの鮮度を保つために、変更後は updateTag , revalidatePath または revalidateTag を呼び出して、関連するキャッシュを更新しましょう。

async function action(formData: FormData) {
  // 指定したタグのキャッシュを即座に無効化(Server Actions専用)
  updateTag("articles")
  
  // 指定したパスのキャッシュを再検証
  revalidatePath("/articles")

  // 指定したタグのキャッシュをバックグラウンドで再検証
  revalidateTag("articles", "max")
}

その他

上記以外にも、「認可」、「レート制限」、「監査ログ」、「冪等性」なども要件に応じて検討が必要です。

📚 Server Actionsと相性のいいライブラリ

Server Actions を使う中で、個人的に体験の良かったライブラリについて紹介します。

next-safe-action

Next.js の Server Actions を型安全に扱うためのライブラリ。
tRPC と似た書き味で Server Actions を書ける。
https://next-safe-action.dev/

import { createSafeActionClient } from "next-safe-action"

// 認証チェックやエラーハンドリングなどを共通化できる
const actionClient = createSafeActionClient({})

export const action = actionClient
  .schema(schema)
  .action(async ({ parsedInput }) => {
    // DBへの保存、外部API呼び出しなどの処理
  })

Conform

型安全なフォームバリデーションライブラリ。
useForm() フックでフォームの状態を管理でき、useActionState との組み合わせで快適に使える。
https://conform.guide/

👀 おわり

最後まで読んでくださり、ありがとうございました!☺️
この記事を通して、少しでも開発のお役に立てば幸いです!

Discussion