接入自己的 Vue 应用

本页面向已有 Vue 3 + Vite 项目的开发者。目标是使用 uAdmin 的内核与布局，同时保留自己的业务页面和登录 UI。

选择需要的包

包	职责	何时直接使用
@uadmin/protocol	信封、会话、导航、权限函数	前后端共享契约
@uadmin/core	HTTP、国际化、指令、工具	独立使用基础能力
@uadmin/ui	页面和数据组件、主题	编写业务页面
@uadmin/layout	侧栏、顶栏、标签页	定制后台布局
@uadmin/app	路由、store、装配与守卫	完整后台入口
@uadmin/modules	插件、菜单、角色、账号等系统页面	需要系统管理功能
@uadmin/extras	可选展示与集成组件	按业务需要接入

安装已发布版本时，可从内核 README 的依赖组合开始：

pnpm add @uadmin/app @uadmin/modules element-plus vue vue-router pinia vue-i18n axios

具体 peer dependencies 以所选版本的 package.json 为准。未发布的仓库版本按本地联调打包验证，不假定远端 registry 已包含当前源码。

配置 Vite

发布包中包含 Vue 源码。消费项目使用内核 Vite 插件，防止预构建与源码加载产生重复的注入键：

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import { uadmin } from '@uadmin/app/vite'

export default defineConfig({ plugins: [vue(), uadmin()] })

对应实现位于 packages/app/vite.mjs。仓库 workspace 与安装后的包解析方式不同，不能因为演示在本地能跑就跳过消费项目验证。

装配应用

下面假设你已经实现 Login.vue 和 Forbidden.vue，后端能返回系统模块导航与会话：

import ElementPlus from 'element-plus'
import { createUAdmin, restBackend } from '@uadmin/app'
import { systemModules } from '@uadmin/modules'
import Login from './Login.vue'
import Forbidden from './Forbidden.vue'

createUAdmin({
  backend: restBackend(),
  modules: systemModules(),
  home: '/system-settings/plugins',
  publicRoutes: [{ path: '/login', component: Login }],
  routes: [{ path: '/errors/403', component: Forbidden }],
  http: { baseURL: '/api' },
  i18n: { messages: { 'zh-CN': {}, 'en-US': {} } },
  setup: app => {
    app.use(ElementPlus)
  },
}).mount('#app')

home 必须是当前账号可用的实际页面。生产项目应按用户权限选择落点；没有系统模块时，用业务模块替换 systemModules()。

登录表单调用 useSessionStore().login({ username, password })，成功后通过 Router 跳转到安全的站内 redirect 或首页。示例省略表单 UI，不代表登录页由内核自动生成。

样式和按需能力

@uadmin/ui 统一加载 Element Plus 基础样式、暗色变量与主题桥接。避免在它之后再次引入 element-plus/dist/index.css，否则主题可能被覆盖。

图表、富文本等较重组件按文档提供的子路径导入，并安装其可选 peer dependency。不要因接入页面壳而一次安装所有展示插件。

后端不符合协议时

BackendAdapter 定义 login、refresh、logout、me、nav 五个方法，位于 packages/app/src/types.ts。可以提供 http => adapter 工厂，在方法中将原有接口字段转换为 Session、Viewer 等协议类型。业务 HTTP 信封与认证适配应一起检查，详见HTTP。

接入验收

确认登录后出现菜单、刷新深链可恢复会话、403 页存在、退出后深链回登录。布局注入警告优先排查 Vite 插件与重复 Vue 依赖；空白首页优先检查 home 和已启用模块。仓库的 pnpm verify:packages 会将 tarball 安装到全新消费项目，适合检查发布边界。