Frontend Troubleshooting

常见坑与排查

前端包的失败多数是静默的：不抛异常，只在页面上显示一句兜底文案。下表把症状映射回原因。

症状速查表

症状（页面显示）	出现位置	最可能的原因
「未找到插件管理页面」	/admin/plugin/<id>/...	① 没用 src/admin.tsx 导出 adminPages；② adminRoutes[].component 与 adminPages 的键不一致；③ 缺少 export default frontend
「未找到插件管理页面」且该插件所有前端页面都不见	任意	缺少 export default frontend（整个包解析失败）
「未找到这个账户页面」	/account/...	ui.accountRoutes[].component 与 ui.accountPages 的键不一致
「无权限访问：需要 <perm>」	/admin/plugin/...	adminRoutes[].permission 未授予当前账号
「你没有访问此页面的权限」	/account/...	accountRoutes[].permission 未授予当前账号
公开页面 404	任意站点路径	没有声明对应 pages；或插件未安装/未启用；或路由被主题/其他插件覆盖
页面正常但 props.data.foo 是 undefined	任意	Finder 名写错、Finder 抛错（平台吞掉错误返回 null）、或 data 未声明该绑定
props.actions['x'] 是 undefined	admin / account 页	ui.actions 里没声明 id 为 x 的操作，或 id 拼错
编译后页面内容还是旧的	任意	没跑 pnpm build:frontend，或没触发 API 重新 seed（touch apps/api/src/app.ts）
后台导航里没有该插件	后台侧栏	adminRoutes[].nav 未声明；或插件未启用

根因详解

1. 缺少 export default frontend

// ✗ 错误：只有命名导出
export const frontend: FrontendPackage = { /* ... */ };

// ✓ 正确：两条都要
export const frontend: FrontendPackage = { /* ... */ };
export default frontend;

平台运行时从入口模块的 default 导出解析前端包（frontend-registry.ts 的 packageOf 取 mod.default ?? mod；构建期探测才额外接受 frontend 命名导出）。缺 default 时，isFrontendPackage 校验失败，该插件的全部页面与路由都会 not-found，且没有任何报错日志。这是最难排查的一类，因为症状看起来像「页面写错了」。

2. 管理后台页面放错了入口

管理后台页面是客户端组件，必须放在 src/admin.tsx：

// frontend/src/admin.tsx
'use client';
export const adminPages = { 'admin/overview': MyAdminPage } as const;

写在 src/index.tsx 的 ui.adminPages 里是无效的——服务端入口打包出的 ui.adminPages 不会被任何渲染方读取。这是官方脚手架早期版本的坑，现已修正；若你手上是旧插件，按管理后台扩展迁移。

3. component 名对不上

三处名字必须一致：

ui.adminRoutes[].component  ──►  admin.tsx 的 adminPages 键
ui.accountRoutes[].component ─►  index.tsx 的 ui.accountPages 键
pages[].component           ──►  index.tsx 的 pageComponents 键

对不上时，平台找不到组件，静默走 not-found 分支。

4. Finder 出错被吞

executePageData / executeRouteData 会 try/catch 掉 Finder 的异常，返回 null。所以 Finder 里 API 404、zod 校验失败等，表现都是「数据没了」而不是报错。排查时可在 Finder 内临时 console.log，或先确认 ctx.api.get 的路径与响应 schema 正确。

5. 编译与热更新链路

改前端源码后必须：

pnpm build:frontend          # 重新编译产物并更新注册表
touch apps/api/src/app.ts    # 内置插件：触发 API 重新 seed

只改后端 src/index.ts 还需要 pnpm --filter <pkg> build。三条命令漏任何一条，看到的都是旧结果。

排查步骤

1. 确认插件已启用：/admin/plugins 里状态为已启用。未启用的插件不进 /plugins/frontends。
2. 确认前端包已构建：data/plugins/<id>/frontend/dist/ 下应有 index.js（以及可能的 admin.js）。
3. 确认注册表已更新：apps/web/src/lib/frontend-registry.ts 应包含 plugins/<id>；若有 admin 页，frontend-client-registry.ts 也应包含它。
4. 对照上面的「根因详解」：优先查 default 导出、入口位置、component 名。
5. 看 API 日志：Finder 异常、权限检查失败会在 API 侧留下线索。

相关

• 管理后台页面入口（src/admin.tsx）
• 前端包介绍：三条硬约束