快速上手
技术栈全景
项目使用的框架、构建工具、状态、UI、样式与工程化方案
一览表
| 领域 | 技术 | 说明 |
|---|---|---|
| 框架 | React 19 | 启用 React Compiler（babel 插件） |
| 语言 | TypeScript 6 | 全仓库 strict，类型即契约 |
| 构建（应用） | Vite | 预设封装在 @skyroc/web-admin-vite |
| 构建（库） | tsdown | 各 @skyroc/* 包统一用 tsdown 出 dist |
| 任务编排 | Turborepo | build / lint / test / typecheck 并行 + 缓存 |
| 包管理 | pnpm 10.4.1 | workspace + catalog 统一版本 |
| 路由 | TanStack Router | 文件式路由，自动生成 routeTree.gen.ts |
| 客户端状态 | Jotai | 封装在 @skyroc/core-state，单一 globalStore |
| 服务端状态 | TanStack Query | 封装在 @skyroc/service/query |
| HTTP | Axios + axios-retry | 封装在 @skyroc/axios，类型安全 |
| UI（业务） | Ant Design 6 | 主题由 OKLCH 算法驱动 |
| UI（设计系统） | @skyroc/web-ui | Radix UI + Tailwind，50+ 组件 |
| 样式 | UnoCSS / Tailwind / Sass | @sa/uno-config、@skyroc/tailwind-plugin |
| 颜色 | colord / culori | @skyroc/color，OKLCH 调色板 + WCAG |
| i18n | i18next / react-i18next | 封装在 @skyroc/web-admin-i18n |
| 动画 | Motion | 懒加载封装 LazyAnimate |
| 日志 | LogLayer | @skyroc/logger，跨端日志上报 |
| 表单 | @skyroc/form | 类型安全表单 primitive |
| Lint | Oxlint | Rust 实现，替代 ESLint |
| 格式化 | Oxfmt | Rust 实现，替代 Prettier |
| 测试 | Vitest + Testing Library | happy-dom 环境，MSW 备用 |
版本来源：pnpm catalog
依赖版本不写死在各包的 package.json，而是集中在 pnpm-workspace.yaml 的 catalogs: 中按域分组，子包用 catalog:<域> 引用。例如：
catalogs:
core:
react: 19.1.0
jotai: ^2.16.0
utils:
axios: ^1.7.9
dayjs: ^1.11.19// 某个包的 package.json
{
"dependencies": {
"react": "catalog:core",
"axios": "catalog:utils"
}
}这样升级一个依赖只需改一处。详见 Catalog 依赖管理。
关键技术决策
- 为什么 Oxlint / Oxfmt 而非 ESLint / Prettier：Rust 实现，性能 50-100×，无需额外 parser。Expo 移动端仍保留 ESLint。
- 为什么 OKLCH 主题算法：相比 Ant Design 默认的 HSV 调色板，OKLCH 色彩空间感知更均匀，便于满足 WCAG 对比度。见
@skyroc/adapter-antd-theme。 - 为什么 Jotai + TanStack Query 双状态：客户端 UI 状态（主题、语言、菜单、标签页）用 Jotai 原子；服务端数据用 React Query 管理缓存与请求生命周期，两者职责分明。
- 为什么文件式路由：TanStack Router 插件扫描
src/pages，自动生成类型安全的路由树，配合autoCodeSplitting自动分包。