3. 插件开发基础：Scaffolder模板、插件目录结构、package.json配置

在Backstage中，插件是功能扩展的基本单元。本章聚焦于插件开发的核心基础：Scaffolder模板（快速生成插件骨架）、插件目录结构（约定优于配置）以及package.json配置（元数据与依赖管理）。掌握这三部分，是构建隔离良好、可维护的插件的第一步。

3.1 使用Scaffolder模板创建插件

Backstage内置了强大的Scaffolder（脚手架）系统，用于快速生成标准化的插件项目结构。推荐使用npx @backstage/create-app或yarn create backstage-app后，通过以下命令创建插件：

# 在Backstage根目录下执行
yarn new --select plugin

# 或使用backstage-cli
yarn backstage-cli new plugin my-plugin-name

执行后，Scaffolder会交互式询问插件名称、是否包含后端、是否包含React组件等选项。生成的插件骨架遵循官方最佳实践，自动配置了TypeScript、ESLint、Jest等工具链。

3.2 插件目录结构详解

一个标准的Backstage插件（以my-plugin为例）通常包含以下目录与文件：

3.3 package.json配置要点

插件的package.json是Backstage识别和加载插件的核心配置文件。除了标准的npm字段外，还包含Backstage特有的元数据。

3.3.1 核心字段说明

3.3.2 典型package.json示例

{
  "name": "@internal/plugin-capacity-planner",
  "version": "0.1.0",
  "main": "dist/index.esm.js",
  "types": "dist/index.d.ts",
  "license": "Apache-2.0",
  "backstage": {
    "role": "frontend-plugin",
    "pluginId": "capacity-planner",
    "pluginPackages": [
      "@internal/plugin-capacity-planner"
    ]
  },
  "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"
  },
  "dependencies": {
    "@backstage/core-plugin-api": "^1.9.0",
    "@backstage/plugin-catalog-react": "^1.12.0",
    "@material-ui/core": "^4.12.2",
    "react": "^17.0.2",
    "react-router-dom": "^6.3.0"
  },
  "devDependencies": {
    "@backstage/cli": "^0.26.0",
    "@testing-library/jest-dom": "^6.0.0",
    "@testing-library/react": "^12.1.0"
  },
  "peerDependencies": {
    "react": "^16.13.1 || ^17.0.0"
  }
}

3.4 插件入口与导出规范

每个插件必须通过src/index.ts导出核心内容，Backstage的App Builder通过扫描这些导出加载插件。

3.4.1 标准导出结构

// plugins/my-plugin/src/index.ts
export { myPluginPlugin } from './plugin';
export { MyPluginPage } from './components/MyPluginPage';
export { MyPluginCard } from './components/MyPluginCard';
export type { MyPluginApi } from './types';

3.4.2 plugin.ts 核心定义

// plugins/my-plugin/src/plugin.ts
import { createPlugin, createRoutableExtension } from '@backstage/core-plugin-api';
import { rootRouteRef } from './routes';

export const myPluginPlugin = createPlugin({
  id: 'my-plugin',
  routes: {
    root: rootRouteRef,
  },
});

export const MyPluginPage = myPluginPlugin.provide(
  createRoutableExtension({
    name: 'MyPluginPage',
    component: () => import('./components/MyPluginPage').then(m => m.MyPluginPage),
    mountPoint: rootRouteRef,
  }),
);

3.5 开发环境与调试

插件开发时，建议使用dev/index.ts创建独立的开发入口，避免影响主应用：

// plugins/my-plugin/dev/index.ts
import { createDevApp } from '@backstage/dev-utils';
import { myPluginPlugin, MyPluginPage } from '../src';

createDevApp()
  .registerPlugin(myPluginPlugin)
  .addPage({
    path: '/my-plugin',
    title: 'My Plugin',
    element: <MyPluginPage />,
  })
  .render();

运行yarn start后，可在独立端口（通常为:3000）预览插件，与主应用完全隔离，便于快速迭代和故障排查。