Next.js中使用useContext Hook报错如何排查解决

报错核心原因 #

该报错是Next.js场景下使用useContext的高频问题，触发原因共三类：

• 违反React Hook调用规则：useContext没有写在函数组件/自定义Hook的顶层作用域，在普通工具函数、组件外层、条件判断、循环逻辑、事件回调内部调用了Hook
• Context作用域不匹配：调用useContext消费Context的组件，没有被对应的Context.Provider包裹，无法获取上下文值
• App Router端组件混用问题：Next.js 13+ App Router模式下组件默认是服务端组件，服务端组件不支持useContext这类客户端Hook，直接调用就会抛出错误

分步修复方案 #

1. 修正Hook调用位置 #

严格遵守React Hook调用规则：

useContext只能在函数组件顶层、自定义Hook顶层调用，不能嵌套在其他逻辑块内。

错误写法示例：

// 错误：组件外层全局作用域调用Hook
const ctxValue = useContext(MyContext)
export default function BlogPage() {
  return <div>{ctxValue}</div>
}

正确写法：

export default function BlogPage() {
  // 正确：组件顶层作用域调用
  const ctxValue = useContext(MyContext)
  return <div>{ctxValue}</div>
}

2. 正确配置Context Provider #

如果是全局使用的Context，需要将Provider放到根layout.js中包裹所有子路由，确保所有消费Context的组件都在Provider作用域内。
注意Provider组件必须标记为客户端组件：

// app/context-provider.js
'use client' // 必须加该指令，否则服务端组件不支持Context能力
import { createContext, useState } from 'react'
// 导出Context实例供useContext调用
export const AppContext = createContext(null)

export default function AppContextProvider({ children }) {
  const [userInfo, setUserInfo] = useState(null)
  return (
    <AppContext.Provider value={{ userInfo, setUserInfo }}>
      {children}
    </AppContext.Provider>
  )
}

在根layout中引入并包裹子内容：

// app/layout.js
import AppContextProvider from './context-provider'

export default function RootLayout({ children }) {
  return (
    <html lang="zh-CN">
      <body>
        <AppContextProvider>
          {children}
        </AppContextProvider>
      </body>
    </html>
  )
}

3. 处理客户端/服务端组件边界 #

所有直接调用useContext消费Context的组件，文件顶部必须加'use client'指令标记为客户端组件。
不需要把所有用到Context值的组件都标记为客户端组件，只有直接调用useContext的消费层需要加客户端标记，下层通过props接收Context值的组件依然可以保留服务端组件身份，不影响性能。

内容的提问来源于stack exchange，提问作者Harjot Singh