紀錄工作經驗、相關知識,解決技術相關問題。

Next

Next.js use server 指令用法:Server Function 寫法、表單呼叫、可序列化參數與安全性

Next.js use server 指令用法:Server Function 寫法、表單呼叫、可序列化參數與安全性 特色圖片

'use server' 指令用來標記 Server Function:在伺服器執行、但可以從瀏覽器端呼叫的 async 函式。寫在檔案頂端時,整個檔案匯出的函式都是 Server Function;寫在函式本體第一行時,只標記那一個函式。本文以 Next.js 16(範例在 16.4.3、React 19.3.0 執行)說明 use server 的兩種寫法、從表單與 Client Component 呼叫的方式、參數與回傳值的序列化限制,以及官方要求的安全檢查。Server Component 與 Client Component 的邊界、'use client' 的寫法規則,可以先看 Next.js use client 指令用法。

use server 的兩種寫法

檔案層級:檔案內匯出的函式都是 Server Function

把 'use server' 寫在檔案第一行,這個檔案匯出的每個函式都在伺服器執行。要讓 Client Component 呼叫 Server Function,只能用這種寫法:

// app/tests/nextjs-use-server-directive/actions.ts
'use server'

let likes = 0

export async function incrementLike() {
  likes++
  return likes
}

export async function inspectArgs(createdAt: Date, tags: Map<string, number>, form: FormData) {
  return {
    createdAtIsDate: createdAt instanceof Date,
    tagsIsMap: tags instanceof Map,
    tagsSize: tags.size,
    formTitle: String(form.get('title')),
    runtime: `Node.js ${process.version}`,
  }
}

函式層級:在 Server Component 裡寫 inline Server Function

在 Server Component 內的 async 函式本體第一行寫 'use server',就只標記這個函式。下面的 addNote 直接交給 <form action>:

// app/tests/nextjs-use-server-directive/page.tsx(Server Component)
import { revalidatePath } from 'next/cache'
import { notes } from './store'
import LikeButton from './like-button'
import ArgsDemo from './args-demo'

export default function Page() {
  async function addNote(formData: FormData) {
    'use server'
    const text = String(formData.get('note') ?? '').trim()
    if (!text) return
    notes.push(text)
    revalidatePath('/tests/nextjs-use-server-directive')
  }

  return (
    <main>
      <h1>use server 範例</h1>
      <form action={addNote}>
        <input name="note" placeholder="留言內容" />
        <button type="submit">送出</button>
      </form>
      <ul>
        {notes.map((n, i) => (
          <li key={i}>{n}</li>
        ))}
      </ul>
      <LikeButton />
      <ArgsDemo />
    </main>
  )
}

store.ts 只是放示範資料的模組,加上 import 'server-only' 避免被打包進用戶端:

// app/tests/nextjs-use-server-directive/store.ts
import 'server-only'

export const notes: string[] = ['第一則留言']

revalidatePath 讓這個路徑的快取失效,Server Action 會在同一個請求裡重新渲染目前頁面,送出後清單就會出現新留言。

寫法規則

React 文件列出的限制:

  • 指令必須寫在函式或模組的最開頭,在所有程式碼(包括 import)之前;上方可以有註解。
  • 只能用單引號或雙引號,不能用反引號。
  • 只能用在 async 函式,因為呼叫 Server Function 背後一定是非同步的網路請求。
  • 要讓 Client Component import Server Function,指令必須寫在模組層級(檔案頂端)。

檔案頂端有 'use server',卻匯出一般函式時,Next.js 會在編譯時報錯:

'use server'

export function getRuntime() {
  return process.version
}
Next.js 16.4.3 Build Error 畫面:Server Actions must be async functions,標出 getRuntime 函式

Next.js 16.4.3(Turbopack)next dev 錯誤畫面,Chrome 無頭模式,Windows 11

Error: Server Actions must be async functions.

把 'use server' 寫在 import 下一行,則會出現:

Error: The "use server" directive must be at the top of the file.

在表單中呼叫:form action 收到 FormData

把 Server Function 傳給 <form action>,使用者送出表單時,React 會把表單的 FormData 當成第一個參數傳進去,所以上面的 addNote 用 formData.get('note') 取值。

這種寫法支援漸進式增強:Server Component 裡呼叫 Server Action 的表單,在 JavaScript 還沒載入或被停用時一樣能送出。下面兩張圖分別是一般操作,以及停用 JavaScript 後送出表單的結果:

use server 範例頁:用 form action 新增留言、按讚 2 次,檢查參數型別回傳 createdAtIsDate true、tagsIsMap true

Next.js 16.4.3 next dev,Chrome 無頭模式送出表單、按讚兩次與檢查參數型別後的畫面,Windows 11

停用 JavaScript 後送出表單,清單新增「停用 JavaScript 送出」,按讚按鈕維持 0

Chrome 無頭模式停用 JavaScript 後按 Enter 送出表單的結果,Next.js 16.4.3,Windows 11

停用 JavaScript 時,瀏覽器以一般表單 POST(multipart/form-data)送到目前頁面,伺服器執行 addNote 後回傳新的 HTML,清單多了一筆。按讚按鈕靠 onClick,沒有 JavaScript 就不會動作。Next.js 的 Server Action 只接受 POST 方法。

在 Client Component 呼叫 Server Function

Client Component 不能自己定義 Server Function,只能從頂端寫了 'use server' 的檔案 import。在 Client Component 裡寫 inline 'use server' 會直接報錯:

'use client'

export default function Page() {
  async function save() {
    'use server'
    console.log('save')
  }
  return <button onClick={() => save()}>Save</button>
}
Next.js 16.4.3 Build Error 畫面:It is not allowed to define inline use server annotated Server Actions in Client Components

Next.js 16.4.3(Turbopack)next dev 錯誤畫面,Chrome 無頭模式,Windows 11

Error: It is not allowed to define inline "use server" annotated Server Actions in Client Components.
    To use Server Actions in a Client Component, you can either export them from a separate file with "use server" at the top, or pass them down through props from a Server Component.

錯誤訊息給了兩個解法:把函式移到 'use server' 檔案再 import,或由 Server Component 以 props 傳下來。Server Function 本身是可序列化的 props,所以後者也成立。

從 actions.ts import 後,在事件處理器呼叫。表單以外的呼叫,React 建議包在 Transition 裡,才能顯示載入狀態;<form action> 與 formAction 會自動包進 Transition:

// app/tests/nextjs-use-server-directive/like-button.tsx
'use client'

import { useState, useTransition } from 'react'
import { incrementLike } from './actions'

export default function LikeButton() {
  const [likes, setLikes] = useState(0)
  const [isPending, startTransition] = useTransition()

  return (
    <p>
      <button
        disabled={isPending}
        onClick={() => {
          startTransition(async () => {
            const count = await incrementLike()
            setLikes(count)
          })
        }}
      >
        {isPending ? '送出中…' : '按讚'}
      </button>
      :{likes}
    </p>
  )
}

await incrementLike() 拿到的是伺服器回傳的數字,按兩次後畫面顯示 按讚:2。要依回傳值顯示表單驗證錯誤、送出中狀態,React 提供 useActionState,完整寫法可以看 React 19 useActionState 教學:Server Actions 表單驗證、保留欄位與 useFormStatus 送出狀態。

參數與回傳值必須可序列化

從用戶端呼叫 Server Function 時,參數會序列化後透過網路送到伺服器,回傳值也一樣序列化送回來。React 文件列出的參數支援範圍:

支援不支援
string、number、bigint、boolean、undefined、nullReact 元素與 JSX
以 Symbol.for 全域註冊的 symbol沒有全域註冊的 Symbol,例如 Symbol('my new symbol')
內容可序列化的 String、Array、Map、Set、TypedArray、ArrayBuffer一般函式(包括元件函式),Server Function 除外
Date、FormDataclass 本身、class 的實例(上述內建型別除外)
用物件字面值建立、屬性可序列化的純物件null prototype 的物件
Server Functions、Promise事件處理器收到的事件物件

回傳值的支援範圍,和 Server Component 傳給 Client Component 的可序列化 props 相同。

下面的 Client Component 把 Date、Map、FormData 傳給前面的 inspectArgs:

// app/tests/nextjs-use-server-directive/args-demo.tsx
'use client'

import { useState } from 'react'
import { inspectArgs } from './actions'

export default function ArgsDemo() {
  const [result, setResult] = useState('')

  async function run() {
    const form = new FormData()
    form.set('title', 'hello')
    const r = await inspectArgs(new Date(), new Map([['next', 16]]), form)
    setResult(JSON.stringify(r))
  }

  return (
    <p>
      <button onClick={run}>檢查參數型別</button>
      <output>{result}</output>
    </p>
  )
}

伺服器收到的仍是 Date、Map 與 FormData,回傳結果:

{"createdAtIsDate":true,"tagsIsMap":true,"tagsSize":1,"formTitle":"hello","runtime":"Node.js v22.20.0"}

傳入不支援的型別

把函式、class 實例或 onClick 收到的事件物件直接傳給 Server Function,在 Next.js 16.4.3 呼叫當下不會報錯,next dev 終端機記錄成 run([unserializable])。伺服器端拿到的參數讀不到內容,讀取屬性時拋出:

Cannot access x on the server. You cannot dot into a temporary client reference from a server component. You can only pass the value through to the client.

所以事件處理器裡要先取出需要的值(例如 e.currentTarget.value),再把字串或數字傳給 Server Function,不要直接傳事件物件。

安全性:每個 Server Function 都是公開端點

'use server' 讓編譯器把 client bundle 裡的函式實作換成 action ID 加上派送器,實作留在伺服器,但任何人都能送出同樣的 POST 請求呼叫它。官方的要求:

  • 每個 Server Function 內都要驗證身分與授權:只在登入後的頁面才渲染表單不算安全邊界,請求可以不經過 UI 直接送出。
  • 身分從 cookies 或 headers 讀取:不要把 token 當函式參數接收。
  • 驗證輸入:參數完全由用戶端控制,FormData、查詢參數與 headers 都要當成不可信任的輸入。
  • 限制回傳值:回傳值會序列化送到用戶端,只回傳 UI 需要的資料,不要回傳整筆資料庫紀錄。
'use server'

import { cookies } from 'next/headers'

export async function deleteNote(id: string) {
  const session = (await cookies()).get('session')?.value
  if (!session) {
    throw new Error('Unauthorized')
  }
  if (!/^\d+$/.test(id)) {
    throw new Error('Invalid id')
  }
  // 依 session 查出使用者,確認擁有這筆資料後才刪除
  return { ok: true, id }
}

從 Client Component 呼叫的結果:沒有 session cookie 時拋出 Unauthorized;有 cookie、id 為 '42' 時回傳 {"ok":true,"id":"42"};id 為 '42 OR 1=1' 時拋出 Invalid id。

Next.js 另外提供幾項框架層的保護,但官方說明這些不能取代上面的應用層檢查:

保護說明
CSRF 檢查比對請求的 Origin 與 Host(或 X-Forwarded-Host),不符就拒絕;經過代理或 CDN 時用 serverActions.allowedOrigins 設定允許的網域
請求大小上限預設 1MB,需要更大時設定 serverActions.bodySizeLimit
加密 action ID建置時產生加密且不可預測的 action ID;沒有用到的 Server Function 會從 client bundle 移除,不會成為公開端點
閉包變數加密inline Server Action 捕獲的變數送到用戶端前會加密;多台機器或自架部署要設定固定的 NEXT_SERVER_ACTIONS_ENCRYPTION_KEY

傳 2MB 字串給 Server Function 時,next dev 終端機出現的錯誤:

⨯ Error: Body exceeded 1 MB limit.
To configure the body size limit for Server Actions, see: https://nextjs.org/docs/app/api-reference/next-config-js/serverActions#bodysizelimit

同一次呼叫在瀏覽器端拿到的是 TypeError: Failed to fetch,畫面上看不出是大小超過上限,排查時要看伺服器記錄。

使用 use server 的其他注意事項

  • 用來改資料,不是用來取資料:React 文件說明 Server Functions 是為了更新伺服器狀態而設計,不建議拿來取資料,框架通常一次處理一個 action,也無法快取回傳值。讀取資料放在 Server Component 裡做。
  • 同一個用戶端一次只送一個 Server Action:Next.js 會讓後觸發的 action 等前一個完成,用 Promise.all 同時呼叫多個 Server Action 不會平行執行。需要平行處理時,在單一 Server Action 內部處理,或在 Server Component 平行取資料。
  • redirect 寫在 try 區塊外:redirect() 以拋出錯誤的方式中斷執行,寫在 try 裡會被 catch 攔下;呼叫之後的程式碼不會執行,需要新資料的話,在 redirect 前先呼叫 revalidatePath 或 revalidateTag。

use server 修改資料後要更新快取時,updateTag、revalidateTag 與 'use cache' 的搭配可以參考 Next.js use cache 指令用法;onClick 等事件處理器的寫法可以看 React 事件處理器 (Event Handlers)。

參考資料與延伸閱讀

發佈留言