'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(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 後送出表單的結果:

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

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(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、null | React 元素與 JSX |
以 Symbol.for 全域註冊的 symbol | 沒有全域註冊的 Symbol,例如 Symbol('my new symbol') |
內容可序列化的 String、Array、Map、Set、TypedArray、ArrayBuffer | 一般函式(包括元件函式),Server Function 除外 |
Date、FormData | class 本身、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)。
參考資料與延伸閱讀
- Next.js Docs: use server
- Next.js Docs: Mutating Data
- Next.js Docs: Server Actions and Mutations
- Next.js Docs: Data Security
- Next.js Docs: redirect
- React Docs: 'use server'
- React 事件處理器 (Event Handlers):常用事件速查表、SyntheticEvent 與傳參寫法
- Next.js use client 指令用法:Client Component 邊界、可序列化 props 與常見錯誤
- React 19 useActionState 教學:Server Actions 表單驗證、保留欄位與 useFormStatus 送出狀態
- Next.js use cache 指令用法:函式、元件與檔案層級快取、cacheLife 與 cacheTag
發佈留言