Backstage 前端插件脚手架实战从yarn new生成插件到独立运行与验证【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage本篇技术指南以 Backstage 官方 golden-path 教程的前端插件第一步为主线完整讲解如何通过 CLI 的yarn new --select frontend-plugin命令在当前仓库中脚手架出一个全新的前端插件包逐文件剖析脚手架生成的代码结构并给出在完整应用与独立开发服务器两种模式下运行、验证插件的完整步骤。读完本文你将掌握 Backstage 新前端系统Frontend System下插件包的创建流程、createFrontendPlugin/PageBlueprint的插件定义方式以及常见的脚手架故障排查方法。在开始之前环境与前置条件脚手架插件的第一步是确保你的仓库处于可构建状态。根据官方 golden-path 文档与 CLI 模块文档有两个关键前置条件安装依赖必须在仓库根目录执行过yarn install否则yarn new在安装阶段可能失败这也是文档「常见问题」一节明确提到的场景。Node.js 版本匹配确保本机 Node.js 版本与项目要求的版本一致类型检查与脚手架生成依赖 Node 运行时行为。此外需要理解一个关键机制命令中的yarn new并非独立的 CLI 命令而是根目录package.json中定义的 script 别名其背后指向backstage-cli new。这一点可以从 module-new 文档 得到印证——它给出了根package.json中典型的 script 配置{ scripts: { new: backstage-cli new } }backstage-cli new默认会打开一个交互式引导界面而通过--select与--option参数则可以跳过交互、直接生成目标类型的包。用一条命令脚手架出插件在 Backstage 仓库根目录执行以下命令即可创建一个全新的前端插件包yarn new --select frontend-plugin --option pluginIdtodo --option owner命令各部分的含义如下参数作用--select frontend-plugin预选要创建的目标类型为「前端插件」。不传该参数时CLI 会进入完全交互式引导--option pluginIdtodo指定插件 ID 为todo它决定了插件的目录名、路由路径与包名的关键部分--option owner指定插件的维护者/归属信息此处传空字符串表示暂不设置backstage-cli new的完整用法与更多参数可参考 CLI 新模块文档。命令执行完成后会在plugins/todo目录下生成一个新的 NPM 包目录路径取决于你选择的插件 ID包名形如internal/plugin-todo——具体名称取决于传给new命令的参数以及仓库根目录package.json中的相关设置。脚手架生成的目录结构创建插件需要一点时间命令结束后你会得到如下结构的插件包plugins/todo/ ├── dev/ # Standalone dev server setup ├── src/ │ ├── components/ │ │ ├── TodoList/ │ │ └── TodoPage/ │ └── ... # Plugin definition, routes, tests └── package.json这一结构的模板真实存在于本仓库的 packages/cli-module-new/templates/frontend-plugin/ 目录中你可以对照模板.hbs文件理解每个生成文件背后的参数化逻辑例如pluginId、packageName等占位符如何被替换。深入生成的代码你的第一个插件是如何构成的官方 golden-path 系列第二篇「探索生成的代码」逐文件讲解了这些代码的含义这里结合仓库中的模板源码做一次完整剖析。src/plugin.tsx—— 插件定义与页面扩展这是插件的核心定义文件。生成代码对应模板 plugin.tsx.hbsimport { createFrontendPlugin, PageBlueprint, } from backstage/frontend-plugin-api; import { rootRouteRef } from ./routes; export const page PageBlueprint.make({ params: { path: /todo, routeRef: rootRouteRef, loader: () import(./components/TodoPage).then(m ( m.TodoPage / )), }, }); export const todoPlugin createFrontendPlugin({ pluginId: todo, extensions: [page], routes: { root: rootRouteRef, } });关键点解读createFrontendPlugin将插件注册到 Backstage 前端系统中pluginId: todo是全局唯一的插件标识PageBlueprint.make定义了一个「页面扩展」——它声明了应用中的一个路由path: /todo并通过loader对页面组件做懒加载按需加载减少首屏体积rootRouteRef是一个路由引用Route Reference其他插件可以通过它生成指向你插件页面的链接实现插件间的导航互通。其定义本身非常简单见模板 routes.tsimport { createRouteRef } from backstage/frontend-plugin-api; export const rootRouteRef createRouteRef();注意生成代码中的path、pluginId都是模板变量模板文件中的{{pluginId}}会在脚手架时被替换为你传入的插件 ID。也就是说如果你把pluginId改为my-plugin路由路径会相应变成/my-plugin。src/index.ts—— 包入口包的入口文件默认导出插件实例对应模板 index.ts.hbsexport { todoPlugin as default } from ./plugin;默认导出而非命名导出是 Backstage 插件包的约定——这与仓库中 ADR003避免默认导出 讨论的应用代码风格相反插件包本身需要以默认导出形式暴露插件实例以便 feature discovery 机制自动识别。src/plugin.test.ts—— 插件定义冒烟测试脚手架同时生成了插件定义的测试对应模板 plugin.test.ts.hbsimport { todoPlugin } from ./plugin; describe(todo, () { it(should export plugin, () { expect(todoPlugin).toBeDefined(); }); });它验证插件实例能够被正确创建与导出属于最基础的冒烟测试。src/components/TodoPage/—— 页面组件与数据获取TodoPage是插件的主页面组件负责从后端获取数据并渲染对应模板 TodoPage.tsx.hbsimport { Progress } from backstage/core-components; import { useApi, fetchApiRef, } from backstage/frontend-plugin-api; import { Header, Container } from backstage/ui; import useAsync from react-use/esm/useAsync; import { TodoList } from ../TodoList; import type { TodoItem } from ../TodoList; const exampleTodos: TodoItem[] [ { id: 1, title: Install the backend plugin, createdBy: user:default/guest, createdAt: new Date().toISOString() }, { id: 2, title: Connect the frontend to real data, createdBy: user:default/guest, createdAt: new Date().toISOString() }, ]; function useTodos() { const { fetch } useApi(fetchApiRef); return useAsync(async (): PromiseTodoItem[] { const response await fetch(plugin://todo/todos); if (!response.ok) { throw new Error( Failed to fetch todos: ${response.status} ${response.statusText}, ); } const data await response.json(); return data.items; }, [fetch]); } export const TodoPage () { const { value: todos, loading, error } useTodos(); if (loading) { return Progress /; } return ( Header titleWelcome to todo! / Container TodoList todos{error ? exampleTodos : (todos ?? [])} / /Container / ); };这里蕴含了 Backstage 前端系统最重要的 API 使用模式fetchApiRef是 Backstage 提供的 fetch 封装 API在backstage/frontend-plugin-api中导出。它包装了浏览器原生fetch自动完成两件关键事情自动注入认证凭据——无需手动拼接任何Authorization头解析plugin://pluginIdURL scheme——将plugin://todo/todos解析为当前实例后端插件的真实地址例如http://localhost:7007/api/todo/todos具体的解析依赖 discovery 机制开发中无需关心后端地址的配置。useAsync来自react-use在组件挂载时执行异步函数返回{ value, loading, error }组件据此呈现三种状态加载中转圈Progress、后端请求失败时回退到示例数据exampleTodos保证插件开箱即可渲染、成功时展示真实 todo 列表页面通过backstage/ui的Header与Container维持与 Backstage 其他插件一致的视觉风格。src/components/TodoList/—— 纯展示组件TodoList是一个纯展示presentational组件接收 todos 数组作为 props 并渲染成表格见模板 TodoList.tsximport { Table, useTable, CellText, type ColumnConfig } from backstage/ui; export type TodoItem { title: string; id: string; createdBy: string; createdAt: string; }; const columns: ColumnConfigTodoItem[] [ { id: title, label: Title, isRowHeader: true, cell: item CellText title{item.title} /, }, { id: createdBy, label: Created by, cell: item CellText title{item.createdBy} /, }, { id: createdAt, label: Created at, cell: item CellText title{new Date(item.createdAt).toLocaleString()} /, }, ]; export const TodoList ({ todos }: { todos: TodoItem[] }) { const { tableProps } useTable({ mode: complete, data: todos, paginationOptions: { pageSize: todos.length || 1 }, }); return ( Table columnConfig{columns} {...tableProps} pagination{{ type: none }} / ); };TodoItem类型与后端插件返回的数据形状一一对应是前后端约定的数据契约Table、ColumnConfig、useTable均来自backstage/ui。在较新版本的脚手架中UI 组件已从backstage/core-components逐步迁移到统一的backstage/ui包Progress仍来自backstage/core-components。dev/index.tsx—— 独立开发服务器插件还带有一套独立的开发环境模板 dev/index.tsximport { createDevApp } from backstage/frontend-dev-utils; import plugin from ../src; createDevApp({ features: [plugin] });createDevApp会构建一个仅加载当前插件的迷你 Backstage 应用使你可以在不启动整个平台的情况下快速迭代插件 UI。package.json——backstage.role决定构建行为生成的package.json对应模板 package.json.hbs中有两个值得注意的字段{ name: internal/plugin-todo, main: src/index.ts, types: src/index.ts, backstage: { role: frontend-plugin, pluginId: todo }, scripts: { start: backstage-cli package start, build: backstage-cli package build, lint: backstage-cli package lint, test: backstage-cli package test, clean: backstage-cli package clean } }backstage.role: frontend-plugin告知 Backstage 工具链如何构建与对待该包是决定包类型的关键字段所有脚本都委托给backstage-cli package ...因此yarn start、yarn test等操作在插件目录内即可直接使用依赖方面插件默认依赖backstage/frontend-plugin-api、backstage/core-components、backstage/ui、backstage/theme等并将react声明为 peer dependency。运行并验证你的插件在完整应用中验证feature discovery如果你的应用开启了 feature discovery默认开启插件会被自动发现并安装。开启方式是在app-config.yaml中设置这也是仓库根 app-config.yaml 中的默认配置app: packages: allpackages: all表示自动发现应用包依赖中的全部插件你也可以改用include/exclude过滤列表精确控制例如app: packages: exclude: - internal/plugin-todo关于 feature discovery 的完整机制与手动安装方式可参考安装插件文档手动安装适用于未开启 discovery 或需要精确控制插件顺序的场景。确认配置无误后从仓库根目录启动完整应用yarn start然后在浏览器中访问http://localhost:3000/todo路径与你选择的插件 ID 一致。你会看到一个带标题栏和示例数据的 todo 页面如果后端 todo 插件也在运行页面将显示真实数据而非示例数据。独立运行插件如果只想专注于当前插件的开发可在插件目录对应的 workspace 上启动独立开发服务器yarn workspace internal/plugin-todo start这条命令会启动dev/index.tsx中配置的独立开发应用实现秒级热更新的插件级开发体验。常见问题排查官方文档针对脚手架过程中的高频问题给出了三条排查路径插件页面没有显示检查app-config.yaml中app.packages是否设置为all。如果你使用了 include/exclude 过滤规则请确认你的插件包没有被排除在外。yarn new 在安装阶段失败确保你已经在仓库根目录先执行过yarn install并且本机 Node.js 版本与项目要求的版本一致。脚手架后出现 TypeScript 类型错误在仓库根目录运行yarn tsc检查类型错误。新脚手架出的插件应当能够无错误编译——如果报错尝试重新执行yarn install。下一步从脚手架走向完整的插件本文覆盖了插件从创建到运行验证的完整闭环。脚手架只是一个起点golden-path 教程的后续章节会带你深入插件开发的进阶主题建议按顺序继续阅读探索生成的代码进一步理解插件定义、页面组件与 UI 组件之间的协作方式动态配置利用前端系统「配置优先config-first」的特性通过app-config.yaml在不改代码的前提下禁用扩展、修改页面标题甚至用PageBlueprint.makeWithOverridesconfigSchema基于 Standard Schema仓库示例使用 Zod添加自定义可配置项HTTP 客户端深入fetchApiRef与plugin://URL scheme 的协作原理将数据请求抽取为独立 Client 类或借助 OpenAPI schema 生成类型安全的客户端避免前后端漂移测试用 Jest React Testing Library MSW 编写单元测试用 Playwright 编写端到端集成测试。至此你已经掌握了 Backstage 前端插件从「一条命令生成」到「运行验证」再到「进阶扩展」的完整路径可以在此基础上开始构建自己的开发者门户插件了。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考