📚 课程目录第2章环境准备

2. 环境准备：Node.js 与 Yarn 安装、Backstage CLI 工具安装、创建 Backstage 应用骨架

在开始 Backstage 插件开发之前，必须搭建一套标准、可复现的本地开发环境。本章将依次完成 Node.js 与 Yarn 的安装、Backstage CLI 工具的全局配置，以及通过 CLI 快速创建 Backstage 应用骨架。这三个步骤是后续所有插件开发与故障排查实验的基础。

版本对齐建议：Backstage 对 Node.js 版本有严格依赖。建议使用 Node.js 18.x LTS（推荐 18.18 或 18.20）和 Yarn 1.22.x（Classic 版本）。使用 nvm 管理 Node 版本可避免权限与版本冲突问题。

2.1 Node.js 与 Yarn 安装

Backstage 应用本质上是 Node.js 项目，依赖 Yarn 作为包管理器。推荐使用 nvm（Node Version Manager）安装和管理 Node.js 版本，避免系统级权限问题。

2.1.1 安装 Node.js（推荐 nvm 方式）

# 安装 nvm（macOS / Linux）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

# 重新加载 shell 配置
source ~/.bashrc   # 或 source ~/.zshrc

# 安装 Node.js 18 LTS
nvm install 18

# 使用并设为默认
nvm use 18
nvm alias default 18

# 验证版本
node --version   # 应输出 v18.18.0 或更高
npm --version    # 应输出 9.x 或 10.x

Windows 用户注意：Windows 建议使用 nvm-windows 或直接下载 Node.js 18 LTS 安装包。安装后务必重启终端，确保 node 和 npm 命令可用。

2.1.2 安装 Yarn Classic

Backstage 官方推荐使用 Yarn Classic（v1），而非 Yarn Berry（v2/v3）。Yarn Berry 的 PnP 模式与 Backstage 插件系统存在兼容性问题。

# 全局安装 Yarn Classic
npm install -g yarn@1.22.22

# 验证版本
yarn --version   # 应输出 1.22.22

工具	推荐版本	安装方式	验证命令
Node.js	18.x LTS（≥ 18.18）	nvm install 18	`node --version`
npm	随 Node.js 自带（9.x / 10.x）	无需单独安装	`npm --version`
Yarn	1.22.x（Classic）	`npm install -g yarn@1.22.22`	`yarn --version`

2.2 Backstage CLI 工具安装

Backstage CLI 是官方提供的命令行工具集，用于创建应用、管理插件、运行开发服务器和构建生产包。安装方式为全局 npm 包。

# 全局安装 @backstage/cli
npm install -g @backstage/cli

# 验证安装
backstage-cli --version   # 应输出版本号，如 0.25.x 或更高

# 查看可用命令
backstage-cli --help

  CLI 核心命令速查：
  backstage-cli create-app — 创建新的 Backstage 应用骨架
backstage-cli start — 启动开发服务器（在应用目录内执行）
backstage-cli build — 构建生产包
backstage-cli create-plugin — 创建新插件骨架

2.3 创建 Backstage 应用骨架

使用 CLI 的 create-app 命令可以快速生成一个完整的 Backstage 应用骨架，包含前端、后端、插件目录和默认配置。

2.3.1 执行创建命令

# 创建应用骨架（替换 my-backstage 为你的项目名）
backstage-cli create-app --name my-backstage

# 进入项目目录
cd my-backstage

# 安装依赖（首次安装可能需要 3-5 分钟）
yarn install

2.3.2 骨架目录结构说明

创建完成后，应用骨架的目录结构如下：

my-backstage/
├── app-config.yaml          # 应用主配置文件
├── app-config.production.yaml  # 生产环境配置覆盖
├── backstage.json           # Backstage 元数据
├── lerna.json               # Lerna monorepo 配置
├── package.json             # 根 package.json
├── packages/
│   ├── app/                 # 前端应用（React + Material UI）
│   │   ├── src/
│   │   └── package.json
│   └── backend/             # 后端应用（Express + 插件后端）
│       ├── src/
│       └── package.json
├── plugins/                 # 自定义插件目录（初始为空）
└── yarn.lock                # 依赖锁定文件

2.3.3 验证骨架运行

# 启动开发服务器（前端 + 后端同时启动）
yarn dev

# 访问前端界面
# 浏览器打开 http://localhost:3000

# 访问后端 API
# 浏览器打开 http://localhost:7007

首次启动常见问题：

如果 yarn dev 报错端口被占用，检查 3000 和 7007 端口是否已被其他进程使用。
如果依赖安装失败，尝试删除 node_modules 和 yarn.lock，重新执行 yarn install。
确保网络可以访问 npm 和 GitHub Packages 仓库（Backstage 部分依赖托管在 GitHub Packages 上）。

2.4 环境验证清单

完成上述步骤后，使用以下清单逐项确认环境就绪：

检查项	验证命令	预期结果
Node.js 版本	`node --version`	v18.18.0 或更高
Yarn 版本	`yarn --version`	1.22.x
Backstage CLI	`backstage-cli --version`	输出版本号（如 0.25.x）
应用骨架创建	`backstage-cli create-app --name test-app`	目录生成成功，无报错
依赖安装	`cd test-app && yarn install`	安装完成，无红色错误
开发服务器	`yarn dev`	前端 :3000 和后端 :7007 均可访问

常见故障排查：

yarn install 失败：检查网络代理设置，尝试 yarn config set registry https://registry.npmmirror.com 使用国内镜像。
backstage-cli 命令找不到：确认 npm 全局安装路径已加入 PATH 环境变量。
yarn dev 启动后页面空白：打开浏览器开发者工具，检查控制台是否有跨域或模块加载错误。