2. Backstage 环境搭建：Node.js 与 Yarn 安装、Backstage 应用脚手架创建、本地开发环境启动与验证
搭建 Backstage 本地开发环境是进行插件开发与平台集成的第一步。本章将引导你完成从基础运行时安装到应用脚手架创建、再到本地开发环境启动与验证的完整流程。一个稳定、版本一致的环境是后续所有自动化巡检功能开发的基础。
2.1 环境依赖概览
Backstage 基于 Node.js 生态构建，其核心依赖包括 Node.js 运行时与 Yarn 包管理器。下表列出了推荐版本及关键说明：
| 依赖项 | 推荐版本 | 说明 |
|---|---|---|
| Node.js | 18.x LTS（建议 18.20.x） | Backstage 1.x 系列对 Node 18 支持最稳定；Node 20 部分插件存在兼容性问题 |
| Yarn | 1.22.x（Classic） | Backstage 官方脚手架依赖 Yarn Classic；Yarn Berry（v2/v3）暂不推荐 |
| Git | 2.x 及以上 | 用于版本管理与插件模板拉取 |
| 操作系统 | macOS / Linux / Windows（WSL2） | Windows 原生环境可能遇到符号链接问题，强烈建议使用 WSL2 |
版本陷阱提示： 不要直接使用操作系统包管理器（如 apt install nodejs）安装的 Node.js，其版本通常过旧。请使用 nvm（Node Version Manager）或从 Node.js 官网下载 LTS 安装包，确保版本精确可控。
2.2 Node.js 与 Yarn 安装步骤
以下步骤以 macOS / Linux 环境为例，Windows WSL2 用户可完全参照执行。
- 安装 nvm（推荐）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash # 重新加载终端配置 source ~/.bashrc # 或 source ~/.zshrc - 安装 Node.js 18 LTS
nvm install 18 nvm use 18 nvm alias default 18 node --version # 验证输出应为 v18.20.x - 安装 Yarn Classic
npm install -g yarn@1.22.22 yarn --version # 验证输出应为 1.22.22 - 验证核心工具链
node -e "console.log('Node.js 就绪')" yarn --version
快速验证： 如果
node --version 输出 v18.20.x 且 yarn --version 输出 1.22.x，则环境基础已满足 Backstage 运行要求。
2.3 Backstage 应用脚手架创建
Backstage 官方提供了 @backstage/create-app 脚手架工具，用于快速生成标准化的应用骨架。该骨架包含服务目录核心功能、软件模板、技术文档插件等基础模块。
2.3.1 创建应用
npx @backstage/create-app@latest --skip-install
# 根据提示输入应用名称，例如：backstage-capacity-workshop参数 --skip-install 会跳过自动安装依赖，让我们可以手动控制依赖安装过程，便于排查网络问题。
2.3.2 手动安装依赖
cd backstage-capacity-workshop
yarn install依赖安装时间取决于网络状况，通常需要 3-8 分钟。安装完成后，目录结构应包含以下核心模块：
| 目录/文件 | 用途 |
|---|---|
packages/app/ |
前端应用包，包含 UI 组件、路由、插件注册 |
packages/backend/ |
后端服务包，包含 API 路由、数据库连接、认证 |
plugins/ |
自定义插件目录，后续容量巡检插件将在此开发 |
app-config.yaml |
主配置文件，定义集成、代理、数据库等配置 |
catalog-info.yaml |
服务目录实体定义文件，描述组件、API、资源 |
架构理解： Backstage 采用 Monorepo 架构，
packages/app 和 packages/backend 是两个独立的 Node.js 应用，通过 Yarn Workspaces 共享依赖。前端使用 React + Material UI，后端使用 Express + Node.js。
2.4 本地开发环境启动与验证
启动 Backstage 开发环境需要同时运行前端和后端服务。官方脚手架已配置好并行启动脚本。
2.4.1 启动开发服务器
yarn dev该命令会同时启动：
- 前端开发服务器：默认监听
localhost:3000，支持热模块替换（HMR） - 后端开发服务器：默认监听
localhost:7007，支持自动重启
2.4.2 验证启动状态
启动日志中应看到类似以下输出：
[0] webpack compiled successfully
[0] ℹ ｢wdm｣: Compiled successfully.
[1] [backend] Backend started on http://localhost:7007打开浏览器访问 http://localhost:3000，应看到 Backstage 默认首页，包含：
- 左侧导航栏（Home、Catalog、API、Docs 等）
- 首页欢迎卡片
- 右上角用户登录入口（默认使用 Guest 模式）
常见启动问题：
- 端口占用： 如果 3000 或 7007 端口被占用，可在
app-config.yaml中修改app.baseUrl和backend.listen.port。 - SQLite 依赖编译失败： 确保系统已安装
python3和make编译工具链。 - 内存不足： Backstage 开发模式内存占用较高，建议分配至少 4GB 内存给 Node.js 进程。
2.5 环境搭建流程总览
下图展示了从零开始搭建 Backstage 本地开发环境的完整流程与关键节点：
2.6 环境验证清单
完成启动后，建议逐项核对以下验证点，确保环境完全就绪：
| 验证项 | 预期结果 | 验证命令/操作 |
|---|---|---|
| Node.js 版本 | v18.20.x | node --version |
| Yarn 版本 | 1.22.x | yarn --version |
| 前端页面可访问 | Backstage 首页正常渲染 | 浏览器打开 http://localhost:3000 |
| 后端健康检查 | HTTP 200 响应 | curl http://localhost:7007/api/health |
| 服务目录加载 | Catalog 页面显示默认实体 | 点击左侧 "Catalog" 导航 |
| 热模块替换 | 修改前端代码后页面自动刷新 | 修改 packages/app/src/App.tsx 并保存 |