2. 开发环境搭建：Node.js、Yarn、Docker安装、Backstage CLI初始化项目、项目目录结构解析

搭建一个稳定、可复现的开发环境是Backstage插件开发的第一步。本章将指导你完成从基础运行时安装到项目初始化的全流程，并深入解析Backstage默认项目的目录结构，为后续的插件开发打下坚实基础。

2.1 基础运行时安装

Backstage基于Node.js生态，依赖Yarn作为包管理器，并利用Docker容器化技术运行本地数据库和服务。请按以下顺序安装。

2.1.1 Node.js 安装

推荐使用 Node.js 18 LTS 或 20 LTS 版本。Backstage对Node.js版本有严格兼容性要求，低于16或高于21的版本可能导致构建失败。

• 下载地址：https://nodejs.org/（选择LTS版本）
• 验证安装：打开终端执行 node --version 和 npm --version

2.1.2 Yarn 安装

Backstage使用Yarn Classic（v1.x）的Workspaces功能管理多包仓库。请安装Yarn Classic，不要使用Yarn Berry（v3+）。

# 通过npm全局安装Yarn Classic
npm install -g yarn

# 验证安装
yarn --version   # 预期输出 1.22.x

2.1.3 Docker 安装

Docker用于运行Backstage依赖的后端基础设施（如PostgreSQL、Redis等）。本地开发时，Docker Compose用于一键启动这些服务。

• Docker Desktop：适用于Windows和macOS，自带Docker Compose。
• Linux：分别安装 docker-ce 和 docker-compose-plugin。
• 验证安装：docker --version 和 docker compose version

2.2 Backstage CLI 初始化项目

Backstage提供了官方CLI工具 @backstage/create-app，用于快速生成标准项目模板。初始化过程会自动配置Yarn Workspaces、TypeScript、ESLint、Prettier等工具链。

2.2.1 创建新项目

# 使用npx直接创建，无需全局安装
npx @backstage/create-app@latest

# 交互式提示输入项目名称，例如：my-backstage
# 等待依赖安装完成（约3-5分钟，视网络情况而定）

2.2.2 启动开发服务器

# 进入项目目录
cd my-backstage

# 启动开发模式（同时启动前端和后端）
yarn dev

启动成功后，终端会显示前端地址（默认 http://localhost:3000）和后端地址（默认 http://localhost:7007）。打开浏览器访问前端地址，即可看到Backstage默认首页。

2.3 项目目录结构解析

初始化后的Backstage项目采用Monorepo架构，所有代码集中在根目录下，通过Yarn Workspaces管理。理解目录结构是后续插件开发的关键。

2.3.1 顶层目录总览

2.3.2 packages/ 核心包详解

• packages/app：前端应用入口，基于React和Material-UI。包含路由配置、主题定制、全局布局。插件的前端组件在此注册。
• packages/backend：后端服务入口，基于Express和Node.js。负责插件后端逻辑、数据库连接、认证授权、任务调度等。

2.3.3 plugins/ 插件目录约定

每个插件在 plugins/ 下拥有独立子目录，命名规范为 plugin-<name>。一个典型的插件目录结构如下：

plugins/
└── plugin-my-plugin/
    ├── src/                  # 源代码
    │   ├── index.ts          # 插件入口，导出组件和API
    │   ├── components/       # React组件
    │   ├── api/              # API客户端
    │   └── routes.ts         # 路由定义
    ├── dev/                  # 开发环境独立运行入口
    ├── package.json          # 插件级依赖声明
    └── README.md             # 插件文档

2.4 开发环境架构图

下图展示了本地开发环境中各组件之间的通信关系与依赖链路。

2.5 环境验证清单

完成安装后，请逐项核对以下清单，确保环境就绪。