运行时 Provider

这一页聚焦 apps/admin/src/App.tsx 的 React 运行时组合。bootstrap.tsx 负责 React 渲染前的一次性初始化，App.tsx 负责 React context、状态容器、UI 运行时、路由和全局 effect 的依赖顺序。

如果只是新增一个启动前运行一次的插件，优先看 启动流程。如果能力需要 React context、hooks、Provider 或组件生命周期，再看这一页。

适用场景

当前实现位置

Provider 顺序

当前 App.tsx 的组合顺序是：

QueryClientProvider
  -> JotaiProvider
    -> Devtools
    -> AntdProvider
      -> NotificationProvider
        -> LazyAnimate
          -> RouterProvider
          -> GlobalEffect

这不是随意嵌套。每一层都有下游依赖：

Devtools 的边界

AdminDevtools 只在 import.meta.env.DEV 为真时通过 lazy() 动态加载。生产环境使用空组件替代。

Devtools 当前接收四类运行时对象：

这里的主题配置使用 useSettingsTheme() 读取当前暗色模式。不要把 devtools 主题写死，否则暗色模式切换后调试面板会和应用主题脱节。

React Query 缓存

queryClient 是全局单例。当前 createQueryClient() 给 query 和 mutation 都配置了 onError，但只在开发环境打印错误。

认证链路会直接使用这个 queryClient：

如果新增跨页面共享数据，优先进入服务模块的 query hooks，不要在 Provider 里额外创建第二个 query client。

全局插件和 Provider 的区别

不是所有运行时能力都应该放进 App.tsx。

生产环境应用更新检测属于插件。它由 globalConfig.automaticallyDetectUpdate 和 import.meta.env.PROD 共同控制，检测到新版本后通过 notification 提示用户刷新当前路由。

最小新增 Provider 示例

新增 Provider 时，先判断它需要包住哪些下游能力，再放到最近的依赖位置。下面示例展示一个依赖 React Query 的 Provider 应该放在 QueryClientProvider 内部，而不是外部。

import type { ReactNode } from 'react';

interface AdminRealtimeProviderProps {
  /** 需要接收实时事件上下文的应用内容。 */
  children: ReactNode;
}

const AdminRealtimeProvider = (props: AdminRealtimeProviderProps) => {
  const { children } = props;

  return <RealtimeProvider>{children}</RealtimeProvider>;
};

const Provider = (props: ProviderProps) => {
  const { children } = props;

  return (
    <QueryClientProvider client={queryClient}>
      <JotaiProvider>
        <AdminRealtimeProvider>
          <Devtools />
          {children}
        </AdminRealtimeProvider>
      </JotaiProvider>
    </QueryClientProvider>
  );
};

如果新 Provider 需要 Ant Design 静态 API 或通知 context，就应该放在 AntdProvider 或 NotificationProvider 之下。

常见误区

相关链接

• 启动流程
• 登录认证
• 通知系统
• 国际化与图标
• 存储与缓存