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

Next

Next.js use client 指令用法:Client Component 邊界、可序列化 props 與常見錯誤

Next.js use client 指令用法:Client Component 邊界、可序列化 props 與常見錯誤 特色圖片

Next.js App Router 的頁面與 layout 預設都是 Server Component,要用 useState、onClick 或 window 這類只在瀏覽器才有的功能時,就得在檔案第一行加上 'use client' 指令,把這個檔案標記為進入用戶端的入口。本文以 Next.js 16(範例在 16.4.3 執行)說明 use client 的寫法規則、邊界怎麼劃分、props 為什麼必須可序列化,以及 useState、事件處理器、函式 props 放錯地方時的錯誤訊息原文與修正方式。

use client 基本寫法:放在檔案最上方

'use client' 要寫在檔案的最開頭、所有 import 之前,作用範圍是整個模組,不能寫在元件或函式裡面。檔案開頭的註解可以放在指令前面,引號用單引號或雙引號都可以:

// 檔案開頭的註解可以放在指令前面
"use client"

import { useState } from 'react'

export default function Toggle() {
  const [on, setOn] = useState(false)
  return <button onClick={() => setOn(!on)}>{on ? 'ON' : 'OFF'}</button>
}

在 Server Component(例如 page.tsx)直接 import 這個元件使用即可,page.tsx 本身不用加指令:

import Toggle from './toggle'

export default function Page() {
  return <Toggle />
}

指令寫在 import 後面會怎樣

把 'use client' 放到 import 下一行,Next.js 會直接報錯,要求把指令移到檔案最上方:

import { useState } from 'react'
'use client'
Error: The "use client" directive must be placed before other expressions. Move it to the top of the file to resolve this issue.

用反引號寫指令會怎樣

React 規定指令只能用單引號或雙引號。寫成反引號(`use client`)時,它只是一個普通的字串運算式,檔案仍被當成 Server Component,於是錯誤訊息變成「這個模組用了 useState」:

Error: You're importing a module that depends on `useState` into a React Server Component module. This API is only available in Client Components. To fix, mark the file (or its parent) with the `"use client"` directive.

什麼時候需要 use client

Next.js 官方列出需要 Client Component 的情況:

需求例子
State 與事件處理器useState、onClick、onChange
生命週期邏輯useEffect
瀏覽器專屬 APIlocalStorage、window、navigator.geolocation
自訂 Hook內部用到上述功能的 Hook

反過來,取資料、使用 API key 等不能外流的金鑰、減少送到瀏覽器的 JavaScript,這些工作留在 Server Component。React 文件也說明了原因:Server Component 無法互動,onClick 這類事件處理器只能定義在 Client Component,而且 Server Component 不能使用大多數 Hook。

Server Component 使用 useState 的錯誤

沒有加 'use client' 的 page.tsx 直接 import useState,在 next dev 開啟頁面時會出現 Build Error:

// 錯誤情境:Server Component 直接使用 useState
import { useState } from 'react'

export default function Page() {
  const [count] = useState(0)
  return <p>count:{count}</p>
}
Next.js 16.4.3 開發模式錯誤畫面:Server Component 匯入 useState 時顯示 Build Error,提示加上 use client 指令

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

修正方式就是錯誤訊息寫的:把用到 useState 的部分拆成獨立檔案,在第一行加 'use client'。

Server Component 綁定 onClick 的錯誤

Server Component 裡的 <button> 直接寫 onClick,編譯會通過,但渲染時拋出錯誤:

// 錯誤情境:Server Component 直接綁定 onClick
export default function Page() {
  return <button onClick={() => console.log('clicked')}>Click</button>
}
Error: Event handlers cannot be passed to Client Component props.
  <button onClick={function onClick} children=...>
                  ^^^^^^^^^^^^^^^^^^
If you need interactivity, consider converting part of this to a Client Component.

use client 的邊界:import 進來的模組都在用戶端執行

'use client' 劃出的是 Server 與 Client 的模組邊界。一個檔案標記了 'use client',它 import 的模組與它直接渲染的元件都會被打包進 client bundle,所以不需要在每個 Client Component 檔案都加指令,只要加在「被 Server Component 直接渲染的那個檔案」上。

但這個規則只看 import 關係,不看渲染位置。以 children 或其他 props 傳進 Client Component 的 Server Component,不屬於 Client Component 的模組相依樹,仍然在伺服器渲染。下面的範例同時展示這兩件事。

counter.tsx 是邊界入口,加了 'use client',並 import 了 env-label.tsx:

'use client'

import { useState } from 'react'
import EnvLabel from './env-label'

export default function Counter({
  initial,
  createdAt,
  tags,
  children,
}: {
  initial: number
  createdAt: Date
  tags: Map<string, number>
  children?: React.ReactNode
}) {
  const [count, setCount] = useState(initial)

  return (
    <section>
      <h2>Counter(Client Component)</h2>
      <p>count:{count}</p>
      <button onClick={() => setCount(count + 1)}>+1</button>
      <p>createdAt instanceof Date:{String(createdAt instanceof Date)}</p>
      <p>tags 是 Map:{String(tags instanceof Map)},size = {tags.size}</p>
      <EnvLabel from="Counter 內 import" />
      <div>{children}</div>
    </section>
  )
}

env-label.tsx 沒有 'use client',卻用了 useState。因為它是被 Client Component import 的,所以一樣在用戶端執行,不會報錯:

// 這個檔案沒有 'use client',但用了 useState
import { useState } from 'react'

export default function EnvLabel({ from }: { from: string }) {
  const [clicked, setClicked] = useState(false)
  return (
    <button onClick={() => setClicked(true)}>
      EnvLabel({from}):{clicked ? '已點擊' : '未點擊'}
    </button>
  )
}

server-info.tsx 是 Server Component,讀取 process.version,並用 import 'server-only' 確保它不會被打包到用戶端(說明見後面的 server-only 段落):

// Server Component:只能在伺服器執行
import 'server-only'

export default function ServerInfo() {
  return (
    <p>
      ServerInfo(Server Component,以 children 傳入):Node.js {process.version},
      typeof window = {typeof window}
    </p>
  )
}

page.tsx 是 Server Component,把 ServerInfo 當成 children 傳給 Counter:

import Counter from './counter'
import ServerInfo from './server-info'

export default function Page() {
  const tags = new Map([
    ['react', 19],
    ['next', 16],
  ])

  return (
    <main>
      <h1>use client 範例(page.tsx 是 Server Component)</h1>
      <Counter initial={5} createdAt={new Date('2026-11-02T00:00:00Z')} tags={tags}>
        <ServerInfo />
      </Counter>
    </main>
  )
}

點一次「+1」與 EnvLabel 按鈕後的畫面:

use client 範例頁面:Counter 計數為 6,EnvLabel 顯示已點擊,ServerInfo 顯示 Node.js 版本與 typeof window = undefined

Next.js 16.4.3 next dev,Chrome 無頭模式點擊兩個按鈕後的畫面,Windows 11

畫面上可以看到三件事:

  • count 從 initial={5} 變成 6,EnvLabel 顯示「已點擊」:兩個按鈕都在瀏覽器裡運作,EnvLabel 沒有指令也一樣是 Client Component。
  • ServerInfo 顯示 Node.js 版本與 typeof window = undefined:雖然它畫在 Counter 的方框裡,實際上是在伺服器渲染完,把結果傳給 Counter。
  • createdAt 與 tags 傳到 Client Component 後仍是 Date 與 Map,這兩種型別都在可序列化清單內(見下一節)。

React 文件把這個規則講得很明確:'use client' 的邊界畫在模組相依樹上,不是渲染樹,父子渲染關係不保證兩者在同一個環境執行。另外,'use client' 模組被另一個 client 模組 import 時,指令本身沒有作用;只有從 Server Component import 進來的那一層才是邊界。

props 必須可序列化

Server Component 傳給 Client Component 的 props 要經過序列化才能送到瀏覽器。React 文件列出的支援範圍:

支援不支援
string、number、bigint、boolean、undefined、null一般函式(沒有從 client 模組匯出、也沒有標記 'use server')
以 Symbol.for 全域註冊的 symbol沒有全域註冊的 Symbol,例如 Symbol('my new symbol')
內容可序列化的 String、Array、Map、Set、TypedArray、ArrayBufferclass 本身
Dateclass 的實例(上述內建型別除外)
用物件字面值建立、屬性可序列化的純物件null prototype 的物件
Server Functions、JSX 元素、Promise

傳函式給 Client Component 的錯誤

最常踩到的是把函式當 props 傳下去。以下 format 不是事件處理器,而是一般的格式化函式:

// page.tsx(Server Component)
import Price from './price'

export default function Page() {
  return <Price value={1200} format={(n: number) => `NT$ ${n}`} />
}
// price.tsx
'use client'

export default function Price({ value, format }: { value: number; format: (n: number) => string }) {
  return <p>{format(value)}</p>
}
Next.js 16.4.3 錯誤畫面:Functions cannot be passed directly to Client Components,標出 format={function format}

Next.js 16.4.3 next dev Runtime Error 畫面,Chrome 無頭模式,Windows 11

Error: Functions cannot be passed directly to Client Components unless you explicitly expose it by marking it with "use server". Or maybe you meant to call this function rather than return it.
  <... value={1200} format={function format}>
                           ^^^^^^^^^^^^^^^^^

如果 props 名稱是 onClick 這類事件處理器,錯誤訊息會換成前面看過的 Event handlers cannot be passed to Client Component props.,原因相同。

修正方式是讓 Server Component 只傳資料,函式留在 Client Component 檔案裡:

// page.tsx(Server Component)
import Price from './price'

export default function Page() {
  return <Price value={1200} currency="NT$" />
}
// price.tsx
'use client'

function format(n: number, currency: string) {
  return `${currency} ${n.toLocaleString('zh-TW')}`
}

export default function Price({ value, currency }: { value: number; currency: string }) {
  return <p>{format(value, currency)}</p>
}

頁面輸出 NT$ 1,200。確實需要從用戶端呼叫伺服器端邏輯時,要改用標記 'use server' 的 Server Functions,它屬於可序列化清單中的例外。

用 server-only 防止伺服器程式碼被打包進用戶端

'use client' 會把整條 import 鏈帶進用戶端,所以只該在伺服器執行的模組(讀資料庫、帶 API key 的請求)可能被誤 import。Next.js 只會把 NEXT_PUBLIC_ 開頭的環境變數放進 client bundle,其他環境變數在用戶端會被換成空字串,程式不會照預期運作。

在這類檔案加上 import 'server-only',被 Client Component import 時就會報錯。Next.js 內部處理 server-only 與 client-only,安裝這兩個 npm 套件是選擇性的(範例專案沒有安裝 server-only 也能使用)。把前面的 ServerInfo 改由 Client Component import:

'use client'

import ServerInfo from '../server-info'

export default function UsesServerInfo() {
  return <ServerInfo />
}
Error: 'server-only' cannot be imported from a Client Component module

It should only be used from a Server Component.

同一個 ServerInfo 以 children 傳入時不會觸發這個錯誤,因為它不在 Client Component 的 import 鏈上,這正是上一節邊界規則的反面例子。

縮小 use client 的範圍

'use client' 標在哪個檔案,那個檔案以下的 import 鏈都會變成用戶端程式碼。官方建議把指令加在真正需要互動的元件檔,例如 layout 大部分是 Logo 與導覽連結,只有搜尋框需要互動,就只讓搜尋框那個檔案加 'use client',layout 本身維持 Server Component。

Context Provider

Server Component 不支援 React context。要提供全域狀態(例如主題),建立一個接收 children 的 Client Component:

// theme-provider.tsx
'use client'

import { createContext } from 'react'

export const ThemeContext = createContext('light')

export default function ThemeProvider({ children }: { children: React.ReactNode }) {
  return <ThemeContext.Provider value="dark">{children}</ThemeContext.Provider>
}

在 Server Component 的 layout 包住 children:

// layout.tsx(Server Component)
import ThemeProvider from './theme-provider'

export default function Layout({ children }: { children: React.ReactNode }) {
  return <ThemeProvider>{children}</ThemeProvider>
}

底下的 Client Component 用 use(ThemeContext) 讀到 dark:

// theme-label.tsx
'use client'

import { use } from 'react'
import { ThemeContext } from './theme-provider'

export default function ThemeLabel() {
  const theme = use(ThemeContext)
  return <p>目前主題:{theme}</p>
}

官方建議 Provider 放得越深越好,只包需要的 children,不要包整個 <html>,讓 Next.js 更容易最佳化 Server Component 的靜態部分。

沒有加 use client 的第三方元件

第三方套件的元件如果用到 client 專屬功能、但模組本身沒有 'use client',在 Client Component 裡使用正常,直接放進 Server Component 則會報錯。React 文件列出必須在用戶端執行的 API:createContext、react 與 react-dom 的 Hook(use 與 useId 除外)、forwardRef、memo、startTransition,以及 DOM 操作等瀏覽器 API。

解法是自己建立一個加了 'use client' 的檔案,import 該元件後原樣匯出,Server Component 改從這個檔案 import。若你是元件庫作者,官方建議直接在依賴 client 功能的入口檔加上 'use client',使用者就不必自己包一層。

'use client' 與 Server Component 在 App Router 架構中的定位,可以參考 Next.js App Router 與 Pages Router 差異;Client Component 一樣會先在伺服器預先渲染成 HTML,再於瀏覽器 hydrate;Client Component 裡 useEffect 清除函式的寫法可以看 React useEffect TypeError: destroy is not a function 報錯分析。

參考資料與延伸閱讀

發佈留言