DaLuoComponents

Appearance

第 1 步：创建项目并跑通主子应用 ​

本教程从空目录开始，使用 CLI 创建一个基座和一个 Vue 子应用，先在没有后端的情况下跑通“基座登录 → 菜单 → 子应用列表 → 详情页签”。下一章再接 HTTP 接口和独立登录，第三章替换为订单业务页。

本章使用模板已提供的启动、缓存和路由装配。创建后按下文修改配置即可，不需要另外创建 host/runtime 或自行调用 Wujie startApp。

1. 准备环境与确定版本 ​

使用 Node.js 22 LTS 和 npm；模板最低要求 Node.js 18。本教程统一使用 npm，团队使用 pnpm 时可换为对应的 install/run 命令。

sh
node --version
npm --version

以下创建命令要求 registry 已发布包含本教程功能的 @axewo/fin-micro。团队锁定版本时，将两条命令中的 @latest 都替换为同一个已发布版本；保留生成的 package.json 依赖组合，安装后提交 lock 文件。

当前仓库与已发布包

本手册与当前仓库模板同步，仓库修改不会自动进入 npm。仓库内 review 可以用 node packages/fin-micro/cli/index.mjs create ... 生成最新源码，但生成项目仍安装 package.json 指定的依赖；仅换 CLI 路径不代表已安装最新运行库。尚未发布配套包时，先按本地候选包验收取得配套包，不能用旧运行库硬套新模板。

2. 创建两个项目 ​

在准备存放项目的父目录执行。目标目录必须不存在，创建器不会覆盖已有项目，也不会自动安装依赖。

sh
mkdir micro-lab
cd micro-lab
npx @axewo/fin-micro@latest create my-host --template host --layout standard --port 7100
npx @axewo/fin-micro@latest create order-app --template vue --layout standard --app-id order --port 7101
text
micro-lab/
├─ my-host/       # 基座：登录、后台菜单、工作区、页签
└─ order-app/     # 子应用：业务页面、独立登录、本地路由

本教程先使用 standard 公共布局；需要维护自己的完整布局源码时，创建阶段改为 --layout custom，认证和页面接入步骤一致。

打开第一个终端，从 micro-lab 父目录安装基座依赖：

sh
cd micro-lab/my-host
npm install
npm run check:runtime

第二个终端从 micro-lab 父目录安装子应用依赖：

sh
cd micro-lab/order-app
npm install
npm run check:runtime

若终端已经在 micro-lab，只执行 cd my-host 或 cd order-app。两次能力检查都应成功；失败先处理缺包、旧包或版本组合，暂不继续改页面。

3. 配置基座指向子应用 ​

新建 my-host/.env.local，完整内容为：

dotenv
VITE_AUTH_DEMO=true
VITE_MICRO_APP_ID=order
VITE_MICRO_APP_ENTRY=http://localhost:7101

新建 order-app/.env.local，完整内容为：

dotenv
VITE_MICRO_AUTH_MODE=auto
配置本教程的值作用
子应用创建参数 --app-idorder写入子应用身份与启动校验
基座 VITE_MICRO_APP_IDorder登记同一个子应用
子应用 Vite 端口7101子应用资源服务器
基座 VITE_MICRO_APP_ENTRYhttp://localhost:7101子应用 HTML 入口，不是业务 /list 路由

.env.example 只是说明文件，不会自动生效。修改 env 或 Vite 配置后要重启对应服务器。全文统一使用 localhost，不要在联调中交替使用 127.0.0.1，以免 Cookie、存储和 Origin 不一致。

4. 启动并登录基座 ​

两个终端各自在对应项目内运行：

sh
npm run dev

在浏览器地址栏输入 http://localhost:7100/，使用基座开发演示账号 demo / 123456。

预期：登录后出现“演示用户”、本地主页和左侧“业务应用工作区 / 示例记录”。点击“示例记录”，工作区内出现子应用列表，顶部多一个业务页签。嵌入时子应用不会再显示一套登录页和侧栏。

当前没有启动后端。基座开发演示生成固定公开身份、demo:read 权限和列表菜单；子应用展示模板内存示例。注册表保持默认 shareToken:false，本阶段不调用需要认证的业务接口。能看到嵌入页面不表示已经接好了 API 认证。

5. 验证页签与返回 ​

操作应看到的结果
点击列表里的“打开详情页”新增“示例详情 1”页签
输入草稿，点击列表页签未保存守卫先询问；取消则留在详情，确认切换后再次回来仍保留该缓存页草稿
点击详情里的“返回来源”未保存时先确认；确认后详情关闭并回列表
点击详情里的“刷新本页”未保存时先确认；确认后该详情实例重建
浏览器刷新演示身份和授权页签恢复；内存草稿不会跨整页刷新保存

详情组件里的“关闭本页 / 返回来源”调用 sdk.back()，属于功能页主动结束流程。页签栏的关闭按钮使用宿主自己的关闭策略，两种动作不要混为一谈。

6. 单独打开子应用 ​

在浏览器地址栏输入 http://localhost:7101/，会进入 /#/login。这是正常结果：基座的演示账号逻辑只在基座生效，子应用没有内置假登录服务。 尚未接后端时，向独立登录页提交账号不会成功。

下一章提供可运行的本地 API，并接通独立登录：第 2 步：接通认证、菜单和独立登录。

本章涉及的文件 ​

文件当前如何处理
两个项目的 .env.local按上文新建
基座 src/configs/microApps.ts本章保留默认，下一章显式授权可信应用共享认证
子应用 src/main.ts、src/bootstrap.ts、src/App.vue保留生成器提供的生命周期、会话注入、缓存和清理接线
子应用 src/router/index.ts已有 /list、/detail；第三章更换业务权限和视图
基座 src/platform.ts兼容导出；实际接入文件在 src/platform/

卡住时按现象排查 ​

现象先检查什么
npx 找不到包、安装报版本不存在registry、访问权限、团队发布版本；本地生成源码不能解决缺包
check:runtime 报缺少能力安装包是否与模板配套；不要删除检查或用类型断言跳过
基座能登录，点菜单却加载失败7101 是否启动，入口能否直接打开，Network 中 HTML/JS 是否成功
提示 appId 不一致基座 env 的 order 与创建参数是否一致；修改后是否重启
只有基座主页，没有业务菜单是否意外设了 VITE_AUTH_DEMO=false；真实模式需要 session 和 menus 接口
子应用单独打开停在登录页继续第二章接认证，这是独立模式的预期行为
局域网访问被 CORS 拒绝默认只允许本机来源；在子应用 Vite CORS 登记精确可信 Origin

端口启用 strictPort；7100/7101 已被占用时终端会报错，不会静默换端口。