3. 脚手架搭建：使用 npx @backstage/create-app 创建基线项目
本章进入实战环节的第一步——搭建 Backstage 基线项目。通过官方脚手架工具 @backstage/create-app，你将在本地快速生成一个包含核心服务、前端应用和后端插件的标准项目骨架。这个骨架是后续所有控制平面接口调用与插件集成工作的基础。
3.1 环境准备与前置检查
在执行脚手架命令之前，请确保你的开发环境满足以下最低要求。缺失任何一项都可能导致创建失败或运行时异常。
| 依赖项 | 最低版本 | 验证命令 | 说明 |
|---|---|---|---|
| Node.js | 18.x 或 20.x LTS | node --version |
推荐使用 20.x，对 ESM 和性能支持更好 |
| Yarn | 1.22.x (Classic) | yarn --version |
Backstage 依赖 Yarn Classic 的工作空间机制 |
| Git | 2.30+ | git --version |
用于版本管理和后续插件模板下载 |
| Docker (可选) | 20.10+ | docker --version |
本地运行 PostgreSQL 或测试容器化部署时必需 |
版本对齐建议： 如果你同时管理多个 Node.js 版本，建议使用
nvm 或 fnm 切换到 20.x LTS。Backstage 社区对 18.x 的兼容性测试正在逐步减少，使用 20.x 可以避免潜在的依赖安装问题。
3.2 执行脚手架命令
打开终端，进入你希望存放项目的父目录（例如 ~/workspace/），然后运行以下命令：
npx @backstage/create-app@latest命令执行后，交互式 CLI 会引导你完成以下步骤：
- 输入项目名称 —— 例如
backstage-platform，该名称将作为目录名和package.json中的name字段。 - 选择数据库类型 —— 推荐选择
SQLite（开发阶段）或PostgreSQL（生产准备）。本课程后续章节将使用 PostgreSQL 演示控制平面接口的持久化。 - 等待依赖安装 —— 脚手架会自动执行
yarn install，安装约 2000+ 个依赖包，耗时取决于网络状况。
常见失败场景： 如果安装过程中出现
ETIMEOUT 或 ENOENT 错误，请检查网络代理设置，或尝试使用 yarn config set registry https://registry.npmmirror.com 切换到国内镜像源。安装完成后务必执行 yarn install --frozen-lockfile 验证依赖完整性。
3.3 基线项目结构解析
创建成功后，项目根目录的结构如下。理解每个顶层目录和关键文件的职责，是后续插件开发和接口调用的前提。
backstage-platform/
├── app-config.yaml # 全局应用配置（前端+后端）
├── app-config.local.yaml # 本地覆盖配置（不提交到 Git）
├── catalog-info.yaml # 实体目录定义（软件模板、API 等）
├── lerna.json # Lerna 多包管理配置
├── package.json # 根工作空间定义
├── packages/
│ ├── app/ # 前端应用（React + Material UI）
│ │ ├── src/
│ │ │ ├── App.tsx # 前端路由与插件挂载入口
│ │ │ └── ...
│ │ └── package.json
│ ├── backend/ # 后端服务（Express + 插件后端）
│ │ ├── src/
│ │ │ ├── index.ts # 后端启动入口
│ │ │ ├── plugins/ # 后端插件注册目录
│ │ │ └── ...
│ │ └── package.json
│ └── README.md
├── plugins/ # 自定义插件目录（初始为空）
└── yarn.lock
关键文件速查：
app-config.yaml—— 控制平面接口的地址、认证密钥、数据库连接等全局配置均在此文件定义。packages/backend/src/index.ts—— 后端服务的启动入口，所有后端插件和中间件在此注册。packages/app/src/App.tsx—— 前端路由表，决定每个插件页面在哪个路径下渲染。
3.4 启动基线项目并验证
进入项目目录，使用以下命令同时启动前端和后端开发服务器：
cd backstage-platform
yarn dev启动成功后，终端会输出类似以下信息：
backend: [1] 2024-12-01T10:00:00.000Z backstage info Listening on :7007
frontend: [0] 2024-12-01T10:00:01.000Z backstage info webpack compiled successfully
frontend: [0] ℹ ｢wdm｣: Compiled successfully.打开浏览器访问 http://localhost:3000，你应该能看到 Backstage 的默认首页，包含顶部导航栏、软件目录入口和“Create Component”按钮。这表明基线项目已成功运行。
验证控制平面接口可用性： 在浏览器中打开开发者工具（F12），切换到 Network 标签，刷新页面。你应该能看到对
http://localhost:7007/api/catalog/entities 的 GET 请求返回 200 状态码和 JSON 数据。这个端点就是 Backstage 控制平面的核心接口之一——软件目录查询接口。
3.5 基线项目架构总览
下面的 SVG 图展示了基线项目中前端、后端、数据库以及外部控制平面接口之间的调用关系。理解这个架构有助于你在后续章节中定位插件集成点。
3.6 验证清单与常见问题
完成基线项目创建后，请对照以下清单逐项确认，确保环境就绪：
| 检查项 | 验证方法 | 预期结果 |
|---|---|---|
| 前端页面可访问 | 浏览器打开 http://localhost:3000 |
显示 Backstage 默认首页，无白屏或 404 |
| 后端服务健康 | 访问 http://localhost:7007/api/health |
返回 JSON {"status":"ok"} |
| 目录接口可用 | 访问 http://localhost:7007/api/catalog/entities |
返回空数组 [] 或包含默认实体 |
| 配置文件加载 | 查看后端启动日志 | 无 ConfigNotFound 或 ValidationError |
| 依赖安装完整 | 执行 yarn install --frozen-lockfile |
无依赖冲突或缺失警告 |
端口冲突处理： 如果
:3000 或 :7007 已被占用，可以在 app-config.yaml 中修改 app.baseUrl 和 backend.listen.port 字段。修改后需要重新执行 yarn dev 使配置生效。