跳至主要内容

Vue3 脚手架

2026/10/26大约 4 分钟

Vue3 脚手架（am_plugin）

am_plugin 是官方插件前端开发框架（Vue 3 + TS + Vite + Element Plus + qiankun）。它不是业务插件本身，而是"前端开发框架"：用装配脚本把它装配到独立前端工作区 am_frontends/{name}/，构建产物再回写到插件目录。

前后端解耦 · 单一真源

  • 后端骨架真源：基座后台「创建 / 重新生成自定义插件」生成，模板在 am-serve/stub/plugin/*.stub。脚手架不生成任何 PHP。
  • 前端框架真源：am_plugin/，由 am_frontends/create-plugin.mjs 拷贝到独立工作区。
  • 两者通过前端 .env 的 VITE_PLUGIN_ROOT（指向插件根的相对路径）关联：产物写回插件目录，源码不进插件目录——备份/打包插件不会带上前端工程与 node_modules。

环境要求

依赖版本
Node.js≥ 20.19.0
pnpm≥ 8.8.0（仅支持 pnpm）
基座后端am-serve，默认 http://localhost:8787

标准流程

1. 基座后台建插件（生成后端骨架）

插件管理 →「创建自定义插件」，填插件名（am_ 前缀）。需要会员登录能力时勾选「启用会员登录能力」（要求会员中心已安装启用），保存后 manifest 写入 "dependencies"。基座在 am-serve/plugin/{name}/ 生成 manifest.json / Plugin.php / config / 双入口控制器 / 占位视图。

2. 装配前端

cd am_frontends
node create-plugin.mjs am_demo     # 或双击根目录「创建插件脚手架.bat / .sh」

脚本从 am_plugin 拷贝 src/、scripts/、public/ 与全部配置到 am_frontends/am_demo/，生成三份 .env（插件名、base 路径、VITE_PLUGIN_ROOT 已填充），并带上 pnpm-lock.yaml。

不要删 lockfile

装配必须携带 pnpm-lock.yaml。缺失时 pnpm install 会按 ^ 解析到更新的小版本（如 element-plus 2.11→2.14），引发 vue-tsc 类型漂移、构建失败。

3. 开发

cd am_frontends/am_demo
pnpm install
pnpm dev        # https://localhost:3007

独立运行模式即可预览两个入口（见调试矩阵）。要调"基座内 qiankun 加载"形态，在基座插件管理里把入口临时改成本地 dev URL 并置 is_dev:1。

4. 构建落位

pnpm build      # = vite build && vue-tsc --noEmit && tsx scripts/post-build.ts
产物位置
JS/CSS/图片/字体plugin/{name}/public/assets/{js,css,img,fonts}/（两入口共用同一份 UMD bundle）
管理入口视图plugin/{name}/app/view/app/manage.html（注入 window.__PLUGIN_ENTRY__='manage'）
前台入口视图plugin/{name}/app/view/app/index.html（注入 window.__PLUGIN_ENTRY__='front'）

5. 生产 manifest + 访问

entry/manage_entry 回归 /app/{name}、/app/{name}/manage，open_mode:'micro'。管理入口由基座菜单经 qiankun 免登打开；前台入口任何人直访 /app/{name}。

工作区目录

am_frontends/{name}/
├── src/
│   ├── sdk/            # 插件 SDK（见 sdk.md）
│   ├── views/
│   │   ├── index/      # 前台公开页（/index/**，无需登录）
│   │   └── manage/     # 后台管理布局与页面（菜单驱动，需登录）
│   ├── api/            # index(前台) / system(基座) / plugin(本插件管理)
│   ├── router/         # index.ts(前台静态路由) / manage.ts(回退菜单) / core(菜单引擎)
│   ├── components/     # core 通用 + business(am-* 系列)
│   └── main.ts         # qiankun 生命周期 + 入口模式解析
├── scripts/post-build.ts   # 构建后生成双入口视图 + 产物落位
└── vite.config.ts / tsconfig.json / .env* / pnpm-lock.yaml

页面开发分离硬约定

  • 目录：views/index/** = 公开前台；其余 + 菜单驱动 = 管理后台。
  • 接口分层：api/index/** 只调后端 $noNeedLogin 白名单内的接口；前台组件禁止 import 需登录的管理接口层。
  • 依赖：front 页禁止 import 后台强绑定模块（menu store、worktab、菜单守卫）；共享层只允许 sdk/*、utils/*、通用 components/*。
  • 登录态可选：前台依赖登录的功能必须条件渲染 + 未登录降级 UI（<RequireLogin> / requireLogin()），禁止自建登录页、禁止在 front 路由守卫做自动跳转。

管理页路由由菜单动态注册，无后端菜单时回退 router/modules/manage.ts；component 写相对 src/views/ 的字符串路径（由 ComponentLoader 解析，非 import()）。前台页在 router/modules/index.ts 追加标准 import() 静态路由，访问 /index/xxx。

本地调试矩阵

目标方式
前台页面pnpm dev 后访问 https://localhost:3007/#/index/home（无 bridge，等同线上公开形态）
后台页面https://localhost:3007/#/manage/home
基座内调前台manifest entry 指向本地 dev URL，基座打开传 entryType='front'
基座内调后台manifest manage_entry 指向本地 dev URL

dev server 内置代理：/api → 后端（VITE_API_PROXY_URL，默认 http://localhost:8787）。免登登录闭环只能在同域形态体验，跨端口 localStorage 不共享（见免登与会话）。

构建细节

UMD 单 bundle（format='umd'、name=VITE_PLUGIN_NAME）；生产 base /app/{name}/assets/；产物落位以 VITE_PLUGIN_ROOT 为基准，缺失即构建报错；terser 自动 drop_console/drop_debugger；vue-tsc --noEmit 纳入构建，提交前先 pnpm type-check。

FAQ

  • 报"未找到插件后端"：先在基座后台建同名插件再装配。
  • 报"前端工作区已存在"：重装配先删 am_frontends/{name}/。
  • 在 am_plugin 根目录 pnpm build 报缺 VITE_PLUGIN_ROOT：预期行为，脚手架本身不构建，只在工作区构建。
最近更新: