Frontend Manifest

前端清单

frontend/manifest.json 是前端包的核心配置文件，声明前端包提供的所有能力。

⚠️ 它是编译产物，不要手改。 pnpm build:frontend 每次都会根据 src/index.tsx 重新生成它（含 revision、files 等）。手写的字段会被覆盖。要改声明，请改源码里的 frontend 对象，再重新编译。本文描述的是它的结构与含义，供理解与排查使用。

完整示例

{
  "version": "1.0.0",
  "revision": "abc123",
  "entry": "frontend/dist/index.js",
  "pages": [
    { "path": "/", "component": "HomePage" },
    { "path": "/about", "component": "AboutPage" },
    { "path": "/blog/:slug", "component": "BlogPostPage", "layout": "DefaultLayout" },
    { "path": "*", "component": "NotFoundPage" }
  ],
  "layouts": ["DefaultLayout", "SidebarLayout"],
  "finders": ["blogPosts", "categories"],
  "adminRoutes": [
    { "path": "/my-plugin", "component": "AdminHome", "nav": { "label": "管理首页" } }
  ],
  "adminActions": [
    {
      "id": "quick-action",
      "label": "快捷操作",
      "component": "QuickAction",
      "permission": "my-plugin.write"
    }
  ],
  "actions": [
    {
      "id": "create-item",
      "method": "POST",
      "path": "/my-plugin/items",
      "permission": "my-plugin.write"
    }
  ],
  "accountRoutes": [
    {
      "path": "/my-orders",
      "component": "MyOrders",
      "nav": { "label": "历史订单", "group": "费用" }
    }
  ],
  "accountWidgets": [{ "id": "order-summary", "title": "订单摘要", "component": "OrderSummary" }],
  "files": ["frontend/dist/index.js", "frontend/dist/index.js.map"],
  "settingsSchema": {
    "groups": [
      {
        "id": "general",
        "label": "常规",
        "fields": [
          { "name": "title", "label": "站点标题", "type": "text", "default": "StackPanel" }
        ]
      }
    ]
  }
}

字段详解

字段	必填	类型	说明
version	✅	string	前端包版本号
revision	✅	string	内容哈希，每次重建时变化（用于缓存失效）
entry	✅	string	编译入口 JS 文件，固定为 frontend/dist/index.js（内核校验其前缀必须为 frontend/dist/）
pages	—	array	页面路由定义，默认 []
layouts	—	string[]	可用 Layout 名称列表，默认 []
finders	—	string[]	Finder 名称列表，默认 []
adminRoutes	—	array	管理后台路由，默认 []
adminActions	—	array	管理操作组件，默认 []
actions	—	array	声明式插件操作（表单提交），默认 []
accountRoutes	—	array	账户页面路由，默认 []
accountWidgets	—	array	账户 Widget，默认 []
files	✅	string[]	前端包包含的文件列表
settingsSchema	—	object	设置表单 schema

version、revision、entry、files 是必填字段。pages、layouts、finders、adminRoutes、adminActions、actions、accountRoutes、accountWidgets 均有默认值 []，可省略。

校验规则

上传时，内核对前端清单执行严格校验：

• entry 必须存在且文件可读
• 页面路径必须以 / 开头（或为 * 通配）
• 不允许重复的页面路径、组件名
• 不允许重复的 Layout、Finder、adminRoute、adminAction
• 页面引用的 Layout 必须在 layouts 列表中
• adminAction 的 id 必须唯一

详见各子文档：

• 页面路由
• 命名 Layout
• Finder 数据源
• 管理后台扩展
• 设置 Schema

组件命名

component 字段是组件在 pageComponents（页面/账户页）或 adminPages（管理后台页）映射中的键。平台据此从导入的 dist/index.js（或 admin 页面的 dist/admin.js）里取对应 React 组件。

编译源码时，页面/账户页在 src/index.tsx 里以映射键声明：

// frontend/src/index.tsx
export function HomePage() { return <div>Home</div>; }

export const frontend: FrontendPackage = {
  pages: [{ path: '/', component: 'HomePage' }],
  pageComponents: { HomePage },
};

export default frontend; // 必须

管理后台页面则在 src/admin.tsx 里用 adminPages 映射导出（键对应 adminRoutes[].component）：

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

缺少 export default frontend 时，整份前端包解析失败，所有路由静默 not-found。详见前端包介绍：三条硬约束。