快速开始

本页带你从仓库启动开发后台，再构建一个完全不依赖后端的演示版本。命令均在仓库根目录执行。

接入前先评估

你将得到可运行的后台演示应用与可独立接入的能力包，不是已经托管业务数据的 SaaS。适合维护 Vue 3 / TypeScript 代码、需要交付自有管理后台的团队。

要验证的事	从哪里开始	你会得到什么
页面与交互是否适合业务	运行下方演示，修改任务、切换角色、刷新页面	对数据读写、权限边界与工作台的判断
新项目还是已有 Vue 应用	模块开发 / 独立接入	一条业务模块的接线步骤，或已有应用的依赖与初始化清单
能否沿用已有后端	HTTP 契约与后端适配	登录、刷新、用户、导航与响应字段的适配范围
谁负责生产运行	部署指南	构建、API、服务端授权与上线验收的责任边界

投入范围： 界面和内核可以复用；业务 API、生产数据存储、服务端校验与部署仍需由你的团队完成。

授权与服务： 当前能力包元数据标注 MIT，仓库未提供统一许可证文件，商用前应核实所用版本的许可范围。本站没有公开价格、付费服务或 SLA；当前下一步是技术评估，不是购买托管服务。

1. 安装并启动

使用 Node.js 22.12 或更新的受支持版本，以及 pnpm 10。已有仓库时执行：

node --version
pnpm --version
pnpm install --frozen-lockfile
pnpm dev

打开终端显示的开发地址，默认是 http://localhost:5173。端口被占用时以实际输出为准。根脚本会转发到 apps/demo，无需手动移动源码或安装第二份依赖。

pnpm install 的 prepare 脚本会构建协议包。若安装时禁用了生命周期脚本，可执行 pnpm --filter @uadmin/protocol build。

2. 登录并观察权限

账号	密码	初始可见能力
admin	123456	全部业务与系统管理
editor	123456	任务、应用、聊天等编辑者业务
viewer	123456	概览与帮助

先用 admin 打开任务列表，修改一条任务，再查看插件管理和角色管理。切换账号后比较菜单与按钮。账号的最终权限来自当前角色配置；修改角色后，后续会话不一定再与此表的初始状态相同。

开发模式在 Node 开发服务器中执行 Mock，重启服务会恢复内存种子。要体验跨刷新持久化，继续下一步。

3. 运行纯前端产物

pnpm build:demo
pnpm preview

打开 preview 命令显示的地址。此时请求由浏览器 adapter 处理，业务数据写入 localStorage，文件写入 IndexedDB。修改任务后刷新，应仍能看到修改；右上角演示控件可以切换角色或重置数据。

构建命令决定运行方式

pnpm build 是真实后端版本，预览时需要 API 服务。离线体验使用 pnpm build:demo。pnpm preview 只提供已有产物，不会替你重新构建。

4. 找到你要改的文件

• 应用接线：apps/demo/src/main.ts。
• 业务模块与权限：apps/demo/src/modules.ts。
• 任务页面：apps/demo/src/views/tasks/index.vue。
• 任务数据链路：src/api/task.ts → src/hooks/useTaskList.ts → 页面。
• 对应 Mock：apps/demo/mock/tasks.mock.ts。

接下来按首个业务模块增加一个页面，不需要先理解全部组件。

常用命令

命令	作用
pnpm dev:unode	使用 .env.unode 连接本地后端
pnpm docs:dev	启动官网与文档
pnpm typecheck	检查演示应用类型
pnpm test	运行包测试与浏览器 Mock 测试
pnpm build:all	构建共享包、纯前端演示和官网
pnpm test:e2e:static	对已构建演示运行浏览器验收

启动失败时

提示协议包入口不存在： 检查 prepare 是否执行，手动构建 @uadmin/protocol 后重试。

登录请求到了真实 API： 检查 apps/demo/.env.development 和 shell 中同名环境变量；默认开发需要 VITE_USE_MOCK=true。不要用生产 preview 判断开发 Mock 是否开启。

浏览器还是旧页面： 确认访问的是 dev 还是 preview 端口。修改源码后必须重新构建才能更新 preview。

演示数据与截图不同： 浏览器演示会保存你的修改，使用演示重置恢复种子。详细运行模式见环境与构建。