4、创建第一个插件：使用 yarn new 创建插件、插件目录结构、注册到 App
本章是动手实践的第一站。你将通过 Backstage 内置的脚手架工具 yarn new 快速生成一个标准插件，理解其目录结构，并最终将插件注册到 Backstage 应用（App）中，使其在界面中可见。这是后续所有插件开发的基础流程。
4.1 使用 yarn new 创建插件
Backstage 提供了统一的模板生成器，位于根目录的 packages/cli 中。在 monorepo 根目录下执行以下命令即可启动交互式创建流程：
# 在 Backstage 项目根目录执行
yarn new --select plugin命令执行后，CLI 会依次询问以下信息：
| 提示项 | 说明 | 示例输入 |
|---|---|---|
| Plugin ID | 插件的唯一标识符，使用 kebab-case | my-first-plugin |
| Plugin owner | 团队或用户标识，用于 CODEOWNERS | team:platform |
| Plugin description | 简短描述，会写入 package.json | 我的第一个 Backstage 插件 |
提示： 插件 ID 会直接影响目录名、NPM 包名（
@internal/plugin-my-first-plugin）以及路由前缀。建议使用有意义的英文短词，避免使用中文或特殊字符。
创建成功后，终端会输出类似以下信息：
Creating plugin my-first-plugin...
plugins/my-first-plugin/
package.json
README.md
dev/
src/
index.ts
plugin.ts
routes.ts
components/
types/
...
Done.4.2 插件目录结构详解
生成的插件目录遵循 Backstage 官方规范。下面以 plugins/my-first-plugin 为例，说明每个文件/目录的职责：
| 路径 | 类型 | 职责说明 |
|---|---|---|
package.json |
配置文件 | 定义插件名称、版本、依赖、入口文件（main、types） |
README.md |
文档 | 插件使用说明、开发指南 |
dev/ |
目录 | 独立开发环境配置，包含 index.ts 用于本地运行插件 |
src/index.ts |
入口 | 导出插件实例、路由绑定、组件注册 |
src/plugin.ts |
核心 | 定义 createPlugin 实例，注册路由、API、事件 |
src/routes.ts |
路由 | 声明插件内部路由路径常量，供组件引用 |
src/components/ |
目录 | 存放 React 组件，通常包含 ExampleComponent 等 |
src/types/ |
目录 | TypeScript 类型定义，用于 API 响应、组件 Props |
关键理解：
plugin.ts 是插件的“大脑”，它创建了一个 BackstagePlugin 实例；index.ts 是“门面”，对外暴露该实例和主要组件。其他目录按功能拆分，保持代码整洁。
4.3 注册插件到 App
创建插件后，需要将其注册到 Backstage 应用的主入口中，插件才能在前端路由中生效。注册分为两步：
步骤 1：在 packages/app/src/App.tsx 中导入并注册
// packages/app/src/App.tsx
import { MyFirstPluginPage } from '@internal/plugin-my-first-plugin';
// 在 routes 或 FlatRoutes 中添加路由
const routes = (
<FlatRoutes>
{/* ... 其他路由 */}
<Route path="/my-first-plugin" element={<MyFirstPluginPage />} />
</FlatRoutes>
);步骤 2：在 packages/app/src/components/Root/Root.tsx 中添加侧边栏导航
// packages/app/src/components/Root/Root.tsx
import { MyFirstPluginIcon } from '@internal/plugin-my-first-plugin';
// 在 SidebarItem 列表中添加
<SidebarItem icon={MyFirstPluginIcon} to="/my-first-plugin">
我的第一个插件
</SidebarItem>
注意： 如果插件没有导出
MyFirstPluginPage 组件，请检查 src/index.ts 中是否正确导出了 EntityPage 或自定义页面组件。默认生成的插件可能只导出了 ExampleComponent，需要根据实际需求调整。
4.4 验证注册结果
完成注册后，启动开发服务器：
yarn dev在浏览器中打开 http://localhost:3000，你应该能在左侧边栏看到“我的第一个插件”导航项。点击后，右侧主内容区会显示插件默认的示例页面。
4.5 常见问题与排查
- 导航不显示： 检查
Root.tsx中SidebarItem的to属性是否与App.tsx中的Route path一致。 - 页面空白或报错： 打开浏览器开发者工具，查看控制台是否有模块加载错误。常见原因是
package.json中的依赖未安装，或插件入口文件导出不正确。 - 路由冲突： 确保新插件的路由路径不与现有插件（如
/catalog、/settings）重复。
最佳实践： 建议在
dev/ 目录下独立开发插件，通过 yarn workspace @internal/plugin-my-first-plugin dev 启动独立开发环境，避免频繁修改主 App 配置。待插件稳定后再注册到主应用。