常见问题

项目 / 仓库

Q：仓库与 soybean-admin 是什么关系？

同源不同代。

Soybean Admin 系列是 Soybean 团队的中后台模版，原始仓库基于 Vue。本仓库是 React 版本的演进，但底层架构（monorepo + 多包分层 + 跨端规划）做了完整重做，已经不是简单的语言翻译。

Q：为什么不直接用 Refine / Plasmic / 其它现成方案？

本项目把「中后台」当作设计系统 + 业务沉淀而非应用模板。

设计 token、主题算法、可复用业务模块、跨端能力都需要被显式拆包、长期维护，这是一般模板做不到的。

Q：仓库一共有多少个包？

类型	数量
`packages/@core/*`	10
`packages/shared/*`	3
`packages/primitives/*`	1
`packages/web/` + `packages/web/ui/`	12
`internal/*`	3
`apps/*`	4+
`docs/*`	5

详见项目结构。

安装与运行

Q：必须用 pnpm 吗？

必须。仓库依赖 pnpm 的 catalog / workspace 协议，npm / yarn 无法识别 catalog:core 与 workspace:*。

Q：Node 版本？

仓库 engines.node: ">=20"。开发也建议用 LTS（20+）。

Q：第一次启动哪些步骤是必须的？

git clone <url>
cd soybean-admin-react
pnpm install
pnpm build              # 第一次必须，构建所有 @skyroc/* 包
pnpm dev                # 启动所有 dev（admin 默认 5173）

详见快速开始。

Q：`pnpm dev` 占用很多内存？

pnpm dev 默认启动所有包的 dev（library 走 tsdown watch）。

如果只调 admin：
pnpm --filter @skyroc/admin dev
pnpm --filter @skyroc/web-admin-vite dev  # 必须并跑，admin 依赖它
调单个包时配合 --filter 即可。

Q：第一次 `pnpm install` 卡在 sharp / esbuild？

仓库通过 pnpm.onlyBuiltDependencies 显式允许这些包构建脚本。如果网络受限，可以预先：
pnpm config set registry https://registry.npmmirror.com

开发体验

Q：为什么禁止 `useCallback`？

项目把 React Hook 视为语义工具而非性能工具。 useCallback 99% 是过度优化；架构良好的组件不需要它；启用 React Compiler 后更不需要。详见开发约定。

Q：哪些情况能用 `useMemo`？

仅两种：

从逻辑派生一个值（非函数），逻辑非平凡；

官方建议的 demonstrably expensive 计算。

其它一律不允许。

Q：能用 `any` 吗？

工具未硬禁，但 review 不放过。如果真的必须，建议封装到「窄一点」的范围，不要让 any 扩散到调用方。

Q：怎么写后端类型？

所有后端 API 类型集中在 apps/admin/src/typings/api.d.ts，挂在全局 Api.* 命名空间下，业务代码不需要 import：
const user: Api.Auth.UserInfo = ...

构建与发布

Q：admin 应用产物在哪？

apps/admin/dist/（仅静态资源，可直接传 CDN）。

Q：如何只构建一个包？

pnpm --filter @skyroc/web-ui build
# 构建该包及所有上游依赖
pnpm --filter ...@skyroc/web-ui build

Q：CI 缓存怎么命中？

配置 Turborepo Remote Cache（Vercel 或自建 S3）。详见 CI。

Q：发版要做哪些事？

# 1. 在 main 上
pnpm build
pnpm test
# 2. 走向导
sa release
# 3. 推标签
git push --follow-tags

详见 Git 提交与发版。

跨平台与设计

Q：将来要做 RN 版本，需要做什么？

新建 apps/app、packages/native/*；

复用 @skyroc/@core/*、@skyroc/shared/*、@skyroc/primitives/*；

为业务核心包（service / logger / storage 等）注入 RN 端适配器；

UI 在 packages/native/ui 重新实现（与 web 不共用组件）。

详见平台优先、适配器模式。

Q：为什么不用 React Native Web 共用 UI？

Web 与 RN 的布局模型、事件模型、动画模型完全不同。强行共用 UI 会牺牲两端的体验。共用「业务 / 数据 / 状态」即可，UI 各自原生。

跨包 / 跨域问题

Q：为什么我引入新包后 import 报错？

99% 是没把该包写进当前 app 的 dependencies：
// apps/admin/package.json
"dependencies": {
  "@skyroc/<your-pkg>": "workspace:*"
}
然后 pnpm install。

Q：admin 改了某个 `@skyroc/*` 库为什么不生效？

该库需要走 dev watch（自动重 build）：
pnpm --filter @skyroc/<lib> dev
或者更简单：根目录 pnpm dev 一次全开（占内存）。

Q：tsconfig 报错说找不到类型？

多半是漏 extends：
{ "extends": "@skyroc/tsconfig/web-app.json" }
详见 TypeScript 配置。

主题与 UI

Q：怎么切换主题色 / 暗色模式？

在 admin 应用中直接调主题 hook：
import { useTheme } from '@skyroc/web-admin-theme';
const { setThemeColor, toggleDark } = useTheme();
详见 @skyroc/web-admin-theme。

Q：为什么用 OKLCH 而不是 HSL？

因为 HSV / HSL 的「亮度」并不感知均匀。OKLCH 是感知均匀色彩空间，避免 antd 默认算法在同 saturation 不同 hue 下看起来明暗不一的问题。详见 @skyroc/adapter-antd-theme。

测试

Q：现在测了多少？

@skyroc/@core/* + @skyroc/hooks 单元测试基本覆盖，UI 层与 admin 集成测试待补。详见测试。

Q：能用 Jest 吗？

不推荐。仓库统一 Vitest（与 Vite 同生态，TS 零配置，速度快）。

文档

Q：本文档框架是什么？

Fumadocs + Next.js 15。代码位于 docs/project-docs。

Q：文档怎么本地预览？

pnpm --filter project-docs dev
# 默认 http://localhost:3000

Q：写新文档要做哪些事？

在 content/docs/<分类>/ 下新增 *.mdx；

在同目录的 meta.json 把文件名加入 pages 数组；

顶部加 frontmatter：title + description。

其它

Q：仓库的 license？

看根 LICENSE 与各包 package.json.license。模板包标了 MIT；整体仓库以 README 为准。

Q：在哪里提 Issue / PR？

仓库的 GitHub 主页。Issue 请尽量带最小复现，PR 请关联相关 Issue + 说明动机。

常见问题

Q：仓库与 soybean-admin 是什么关系？

Q：为什么不直接用 Refine / Plasmic / 其它现成方案？

On this page