Skyroc Admin React

介绍

Skyroc Admin React 文档入口，面向 apps/admin 的运行机制、架构理解和二次开发

Skyroc Admin React 是一个面向中后台产品的 React 管理端模板。当前文档以 apps/admin 的真实代码为准，解释这个应用如何启动、路由如何生成、菜单和权限如何协作、请求服务如何接入，以及 packages/web/*、packages/@core/* 中的共享能力在应用侧承担什么职责。

它不是一份从旧文档搬来的功能清单，也不是只描述最终效果的产品介绍。这里更关注二次开发时真正会遇到的问题：新增页面放在哪里、登录后为什么要初始化菜单、动态路由和静态权限如何区分、环境变量如何影响代理和构建、共享包的能力应该在什么边界内使用。

适合谁阅读

读者这份文档解决什么问题
准备启动项目的开发者快速确认 Node、pnpm、dev/build/preview 命令和 Mock/代理行为。
准备二次开发后台页面的人理解页面目录、路由元信息、菜单、tabs、权限、请求 hooks 和表格表单封装。
准备接真实后端的人梳理 env、代理、业务 code、token、refresh token、登录态和 React Query 缓存边界。
准备维护共享包的人判断能力应该留在 apps/admin，还是沉到 @skyroc/web-admin-* 或 @skyroc/* 包里。

当前定位

apps/admin 是后台应用的编排层。它负责把主题、布局、路由、认证、菜单、请求、语言、通知和业务页面组合成一个可运行的管理端；共享包提供可复用能力，但不应该隐藏当前应用的启动顺序和业务接入点。

能力当前边界
启动编排main.tsx 进入 bootstrap.tsx，依次初始化主题、后台布局、运行时插件、i18n，再渲染 React 根节点。
应用 ProviderApp.tsx 组合 React Query、Jotai、Devtools、Ant Design、通知、动画、路由和全局副作用。
路由系统apps/admin/src/pages 使用 TanStack Router 约定式路由，由 Vite 插件生成 routeTree.gen.ts。
菜单和权限setupAdminLayouts() 接收 route tree、菜单分类、动态路由加载器和超级角色；后台入口统一走 guardAdminRoute()。
请求服务apps/admin/src/service 按 urls、api、hooks、keys、types 分层，页面优先通过 React Query hooks 使用接口。
主题和语言@skyroc/web-admin-theme、@skyroc/web-admin-i18n 提供运行时能力，apps/admin 负责默认配置、缓存适配和第三方库同步。
构建配置apps/admin/vite.config.ts 使用 @skyroc/web-admin-vite，env、proxy、base、router 插件和产物规则都从这里进入。

技术栈

依赖版本以仓库根 pnpm-workspace.yaml 的 catalog 和 apps/admin/package.json 为准。当前主链路是：

范围当前使用
基础框架React 19、Vite 8、TypeScript 6
路由TanStack Router、约定式路由、routeTree.gen.ts
数据与状态TanStack Query、Jotai
UI 与样式Ant Design 6、UnoCSS、Skyroc Web UI
主题与布局@skyroc/web-admin-theme、@skyroc/web-admin-layouts
国际化与运行时@skyroc/web-admin-i18n、@skyroc/web-admin-runtime、Iconify、Dayjs、NProgress
请求与工具@skyroc/axios、@skyroc/utils、@skyroc/core-state、@skyroc/scripts

旧版介绍中出现的 React Router、Redux Toolkit、旧 Ant Design/Vite 版本、完整用户/菜单/角色 CRUD 等描述，不应直接迁移到这份文档。当前页面和能力要以 apps/admin 的真实实现为准。

架构速览

main.tsx
  -> bootstrap.tsx
    -> setupTheme
    -> setupAdminLayouts
    -> setupAdminPlugins
    -> setupI18n
    -> render App
      -> QueryClientProvider
      -> JotaiProvider
      -> Devtools
      -> AntdProvider
      -> NotificationProvider
      -> RouterProvider
      -> GlobalEffect

这个顺序很重要：主题、布局和运行时插件需要先完成一次性初始化，React Provider 才能读取稳定的运行时状态；路由 Provider 会把登录态、用户信息、菜单初始化和权限上下文交给 TanStack Router；GlobalEffect 负责把主题和语言变化同步到 DOM、缓存和第三方库。

从哪里读起

目标阅读路径
先把项目跑起来快速开始、开发工具配置、项目结构、组件边界
看懂应用怎么启动启动流程、运行时 Provider、布局系统、菜单与标签页
新增页面和路由路由概览、路由元信息、路由守卫、权限、错误与加载页
接入业务接口请求概览、服务模块、代理与后端对接
修改主题、语言和图标主题系统、国际化与图标、存储与缓存
写管理页列表和表单表格与表单、表单规则、Ant Design 全局反馈、示例页面边界
理解 Dashboard 和图表示例图表与 Dashboard、示例页面边界
理解登录和通知登录认证、通知系统
构建部署和排错构建部署、常见问题

首页只提供介绍和导读，不展开安装命令、路由写法、接口示例或部署细节。具体操作应该放到对应专题页，避免入口页变成一篇过长的综合教程。

参考文件

理解或修改 admin 应用时，优先从下面这些文件开始：

事实来源
应用脚本、技术栈、依赖边界apps/admin/package.json、pnpm-workspace.yaml
编辑器、格式化、i18n Ally 和 UnoCSS 提示.vscode/extensions.json、.vscode/settings.json
启动顺序apps/admin/src/main.tsx、apps/admin/src/bootstrap.tsx、apps/admin/src/App.tsx
全局配置apps/admin/src/config.ts、apps/admin/.env*
路由、守卫、权限上下文apps/admin/src/pages、apps/admin/src/features/router、apps/admin/src/features/auth
菜单、布局、tabsapps/admin/src/features/menus、apps/admin/src/pages/(admin)/layout.tsx
请求封装和服务模块apps/admin/src/service
共享后台能力packages/web/*、packages/@core/*、docs/web-kit-docs

快速开始

安装依赖、启动 apps/admin、构建预览，并理解当前 Mock 与脚本约定

On this page

适合谁阅读当前定位技术栈架构速览从哪里读起参考文件