在 React 开发中，Context API 是组件间共享状态的核心工具。然而，一位开发者最近遇到了一个令人困惑的 Bug：在 index.js 中已通过 <CourseContextProvider> 包裹 <App>，但 App.jsx 内调用 useContext(CourseContext) 却总是返回 undefined。这一问题看似简单，却可能隐藏着多个容易被忽视的陷阱。本文将结合 React 运行机制，逐一排查可能的原因，并给出清晰解决方案。

问题重现

典型的代码结构如下：

// index.js
import { CourseContextProvider } from './CourseContext';
import App from './App';

root.render(
  <CourseContextProvider>
    <App />
  </CourseContextProvider>
);

// App.jsx
import { useContext } from 'react';
import { CourseContext } from './CourseContext';
export default function App() {
  const value = useContext(CourseContext);
  console.log(value); // 输出 undefined
  // ...
}

乍看之下，Provider 已包裹 App，useContext 理应拿到 Provider 提供的值，但结果却是 undefined。这种现象通常源于以下几种情况。

原因一：Provider 并未有效包裹目标组件

最常见的原因是 Provider 与 useContext 引用的不是同一个 Context 对象。例如，在 CourseContext.js 中导出的是 const CourseContext = createContext()，但 Provider 却使用了另一个名为 CourseContextProvider 的组件，而该组件内部并没有正确地用 CourseContext.Provider 传递值。更隐蔽的是，如果项目中存在多个版本的 Context（比如通过 npm 链接的本地包），或者文件路径写错导致了重复定义，都会使 Provider 和 useContext 指向不同的 createContext 实例。

解决方案：确保 Provider 组件内部明确使用 CourseContext.Provider，并且 useContext 引用的正是同一个 CourseContext。建议在 CourseContext.js 中统一导出 Context 和 Provider，避免分散定义。

// CourseContext.js
import { createContext, useState } from 'react';

export const CourseContext = createContext();

export function CourseContextProvider({ children }) {
  const [courses, setCourses] = useState([]);
  return (
    <CourseContext.Provider value={{ courses, setCourses }}>
      {children}
    </CourseContext.Provider>
  );
}

此时，App.jsx 应导入 CourseContext 并传入 useContext，而不是重新 createContext。

原因二：组件渲染顺序或条件渲染导致 Provider 未生效

另一个隐蔽的陷阱是 Provider 在某些条件下被延迟渲染或未渲染。例如，在 index.js 中使用了路由、懒加载或错误边界，导致 <App /> 并不直接是 Provider 的子节点。比如：

// index.js 中的错误写法
root.render(
  <Suspense fallback={<Loading />}>
    <Router>
      <Routes>
        <Route path="/*" element={<App />} />
      </Routes>
    </Router>
  </Suspense>
);

此时 App 被嵌套在多层组件中，而 Provider 却被遗漏了。正确的做法是将 Provider 放在所有消费者之上，通常是在路由或懒加载的外层。

此外，如果 CourseContextProvider 内部使用了条件渲染（比如根据某个状态决定是否渲染 children），也可能导致 App 无法获得上下文。需要检查 Provider 的返回逻辑，确保 children 被无条件渲染。

原因三：React StrictMode 的双重渲染导致预期外行为

React 18 的 StrictMode 会在开发模式下对组件进行双重渲染，以帮助发现副作用。但有时这会让开发者误以为 Provider 没有生效。实际上，StrictMode 并不会改变 Context 的值，但可能导致 useEffect 或 useMemo 的依赖分析出现问题。更常见的是，当 Context value 为 undefined 时，双重渲染会暴露 setState 的初始化时机问题。例如，Provider 的 value 是通过异步操作获得的，初始值就是 undefined。

解决方案：检查 Provider 是否在初次渲染时提供了非 undefined 的默认值。在 createContext(defaultValue) 中设置一个有意义的默认值，可以有效避免 useContext 返回 undefined（尽管这不能解决未包裹的问题）。

原因四：Provider 中的 value 对象被重新创建导致子组件无限重渲染

这虽然不会直接导致 undefined，但常常伴随其出现。如果 Provider 的 value 是一个对象字面量，每次渲染都会创建新引用，从而使 useContext 的消费者组件每次都重新渲染。这虽不会让值为 undefined，但会让调试时误以为 Context 丢失。真正导致 undefined 的根源依然是 Provider 未正确包裹或上下文对象不匹配。

综合排查步骤

  1. 确认 Provider 位置：在 index.js 中直接包裹 <App> 而非其他组件。
  2. 检查导入路径：确保 useContext(CourseContext) 中的 CourseContext 与 Provider 中使用的 CourseContext.Provider 来自同一个文件。
  3. 使用 React DevTools：打开开发者工具的 Components 面板，选中 App 组件，查看其上下文（Context）列表，确认是否存在 CourseContext 以及其值。
  4. 打印 Provider 的 value：在 Provider 内部 console.log(value)，确认数据正常。
  5. 移除 StrictMode 测试：暂时注释掉 <StrictMode>，观察问题是否消失（通常不会，但可排除干扰）。
  6. 检查是否有多个 React 副本：在控制台运行 window.React1 && window.React2（实际可用 __REACT_DEVTOOLS_GLOBAL_HOOK__ 相关命令），或检查打包配置避免重复打包。

总结

useContext 返回 undefined 几乎总是因为 Provider 没有被正确放置在组件树的上方，或者 Consumer 引用了错误的 Context 对象。在 React 生态中，保持 Context 创建与导出的单一职责、使用显式的 Provider 组件、以及善用开发者工具，是避免此类问题的关键。希望本文能帮你快速定位问题，让 Context 真正成为高效的状态管理工具，而非调试噩梦。