企业官网建设流程全解析

扩展Paca界面：前端插件微前端开发完全指南（Module Federation实战）

【免费下载链接】pacaAI-native, free, open-source alternative to Jira, Trello, ClickUp & Monday. Built for Scrum teams where humans and AI agents collaborate as equals — on the same board, the same sprints, the same goals. Self-hosted. Fully customizable via config and plugins.项目地址: https://gitcode.com/gh_mirrors/pac/paca

Paca 是一款开源、可自托管的 AI 原生项目管理工具（Jira / Trello / ClickUp 的替代品），它的前端插件体系基于Vite Module Federation构建：主应用作为宿主（Host），插件作为独立构建的微前端远程模块（Remote Entry）被按需懒加载注入。本文带你从零理解 Paca 前端插件的架构，到用 Module Federation 实战开发第一个界面插件。

🧩 Paca 前端插件是什么？

可以把 Paca 的前端想象成一家"商场"：

• 宿主应用（apps/web）是商场本体，提供看板、任务详情、项目设置等页面，并预留了一批"铺位"——也就是扩展点（Extension Point）；
• 插件是入驻的店铺，各自独立打包成一份remoteEntry.js，存放在插件 CDN 或本地静态目录中；
• 只有当用户真正走到某个铺位前，宿主才会懒加载对应插件的代码，未使用的插件一行代码都不会下载。

这种"宿主 + 远程模块"的微前端模式，让插件可以独立开发、独立构建、独立升级，且不会污染宿主应用。插件还能通过 Paca 插件市场 一键安装分发：

⚙️ 架构解析：Module Federation 如何串联插件

整个加载链路非常清晰，全部代码都在 apps/web/src/lib/plugins/ 目录下：

其中第 ④ 步是 Module Federation 的微前端灵魂：宿主在加载容器前先把react、react-dom、@tanstack/react-query注册进共享作用域（share scope），插件组件运行时使用的就是宿主同一份单例，杜绝"两个 React 实例"这类经典事故。

📍 五个可用的界面扩展点

插件可以"开铺"的位置由清单（Manifest）声明，目前开放的界面扩展点如下（详见 docs/plugins/frontend-plugin-system.md）：

以任务详情面板为例，宿主在 task-detail/index.tsx 中预留了插槽，插件面板会自动出现在附件区上方：

🚀 实战：开发你的第一个界面插件

第 1 步：编写插件清单 plugin.json

清单描述插件身份、远程入口和扩展点注册（完整版见 docs/plugins/developer-guide.md）：

{ "id": "com.example.my-plugin", "displayName": "My Plugin", "version": "0.1.0", "frontend": { "remoteEntryUrl": "/plugins/com.example.my-plugin/assets/remoteEntry.js", "extensionPoints": [ { "point": "task.detail.section", "component": "TaskDetailSection", "label": "My Feature", "order": 50 } ] } }

💡id采用反向域名格式且一旦发布就不可更改；order决定面板的默认排序位置。

第 2 步：配置 Vite Module Federation

插件前端是一个普通 Vite + React 项目，关键是把组件**暴露（exposes）出去、把依赖共享（shared）**给宿主：

// vite.config.ts import { federation } from "@module-federation/vite"; export default defineConfig({ plugins: [ react(), federation({ name: "com_example_my_plugin", filename: "remoteEntry.js", exposes: { "./TaskDetailSection": "./src/TaskDetailSection.tsx" }, shared: ["react", "react-dom", "@paca-ai/plugin-sdk-react"], }), ], });

exposes的导出名必须与清单里的component字段一一对应。

第 3 步：编写 React 组件

插件组件通过@paca-ai/plugin-sdk-react接收宿主注入的强类型上下文，包含api（限定在/api/v1/plugins/{pluginId}/下的 HTTP 客户端）、ui（toast、确认框、导航）和meta（插件元信息），完整 API 见 docs/plugins/sdk-reference.md。你只需专注于业务 UI，不需要（也不能）触碰宿主的 React Query 缓存或内部路由状态。

第 4 步：构建并安装

Paca 提供了官方的一键脚本 scripts/install-local-plugin.sh，它会依次完成：构建前端dist/→ 拷贝产物到本地插件存储plugins/local/frontend/<plugin-id>/→ 调用管理 API 注册并启用插件：

scripts/install-local-plugin.sh /path/to/my-plugin --api-key your-api-key

部署层也已就绪：Caddy 会把/plugins/*路径映射为插件静态资源，remoteEntry.js即可被浏览器直接访问。

第 5 步：验证与排错

刷新页面，打开任务详情，你的面板应该已经出现。如果加载失败，宿主只会显示一个内联错误提示 + 重试按钮，其余页面功能完全不受影响。常见问题排查：

• 面板没出现 → 确认插件已启用、component名与exposes一致；
• 报错 "missing get/init" → 构建产物不是合法的 Module Federation 容器；
• 样式/状态错乱 → 检查react是否声明在shared中（必须用宿主单例）。

🛡️ 安全与稳定性模型

• CSP 白名单：插件来源必须在服务器配置的Content-Security-Policy允许列表内，仅支持 HTTPS；
• 最小上下文：宿主只传递每个扩展点约定的上下文对象，插件无法直接访问宿主 React 树；
• 故障隔离：单个插件的加载失败或渲染异常被 ErrorBoundary 捕获，不影响同页其他插件；
• 管理员控制：超级管理员可全局隐藏或拖拽调整插件面板顺序（PATCH /api/v1/admin/plugin-extension-settings）。

📚 延伸阅读

• 前端插件体系架构：docs/plugins/frontend-plugin-system.md
• 插件系统全景与生命周期：docs/plugins/overview.md
• 从 0 到 1 开发完整插件（含后端 WASM）：docs/plugins/developer-guide.md
• 市场目录与安装流程：docs/plugins/marketplace.md
• 宿主端插件加载源码：apps/web/src/lib/plugins/

掌握 Module Federation 的这套"宿主 + 远程模块"玩法，你就能把任何团队定制功能做成可插拔的 Paca 界面插件，独立迭代、独立发布。动手写第一个插件吧！

【免费下载链接】pacaAI-native, free, open-source alternative to Jira, Trello, ClickUp & Monday. Built for Scrum teams where humans and AI agents collaborate as equals — on the same board, the same sprints, the same goals. Self-hosted. Fully customizable via config and plugins.项目地址: https://gitcode.com/gh_mirrors/pac/paca