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

2. 环境准备：Node.js、Yarn、Docker、Backstage CLI 安装与验证

在开始控制平面接口调用与插件开发之前，必须搭建一套标准化的本地开发环境。本章将指导你完成 Node.js、Yarn、Docker 以及 Backstage CLI 的安装、配置与验证，确保所有工具版本对齐 Backstage 1.32+ 的官方要求。

2.1 环境依赖总览

下表列出了 Backstage 开发环境的核心组件及其推荐版本。请严格按照此清单进行安装，版本偏差可能导致插件基线集成失败。

组件	推荐版本	用途	验证命令
Node.js	18.x LTS 或 20.x LTS	JavaScript 运行时，驱动 Backstage 后端与前端	`node --version`
Yarn	1.22.x (Classic) 或 3.x (Berry)	包管理器，用于安装 Backstage 插件与依赖	`yarn --version`
Docker	24.x 或更高	容器化运行 PostgreSQL、Kubernetes 模拟等基础设施	`docker --version`
Backstage CLI	0.26.x (随 @backstage/cli 发布)	脚手架、构建、开发服务器管理	`backstage-cli --version`

版本对齐提示：Backstage 官方在 2025 年 Q1 已全面转向 Node.js 20.x LTS 作为主要支持版本。如果你使用 Node.js 18.x，请确保版本 ≥ 18.17.0，否则可能遇到 TLS 或流处理兼容性问题。

2.2 安装步骤与验证

2.2.1 Node.js 安装

推荐使用 nvm（Node Version Manager）管理 Node.js 版本，便于在多个项目间切换。

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

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

# 安装 Node.js 20.x LTS
nvm install 20

# 使用该版本
nvm use 20

# 验证
node --version   # 应输出 v20.11.0 或更高
npm --version    # 应输出 10.x

Windows 用户注意：Windows 环境下推荐使用 nvm-windows（https://github.com/coreybutler/nvm-windows）或直接使用官方安装包。安装后务必重启终端，确保 PATH 生效。

2.2.2 Yarn 安装

Backstage 项目默认使用 Yarn Classic（v1）作为包管理器。虽然 Yarn Berry（v3）也受支持，但社区插件和模板仍以 v1 为主。

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

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

如果你希望使用 Yarn Berry，需要在项目根目录创建 .yarnrc.yml 并启用 nodeLinker: node-modules 模式，否则 Backstage 的 monorepo 结构可能无法正确解析。

2.2.3 Docker 安装

Docker 用于运行 Backstage 依赖的外部服务（如 PostgreSQL、Redis、Kafka 模拟器）。请根据操作系统选择安装方式：

macOS： 下载 Docker Desktop for Mac，安装后启动 Docker 引擎。
Windows： 下载 Docker Desktop for Windows，确保启用 WSL 2 后端。
Linux： 使用包管理器安装 Docker Engine，例如 sudo apt install docker.io，然后启动服务并添加当前用户到 docker 组。

# 验证 Docker 安装
docker --version          # 应输出 Docker version 24.0.7 或更高
docker compose version    # 应输出 Docker Compose version v2.24.0 或更高

# 测试运行 hello-world
docker run hello-world

  关键配置：Backstage 的本地开发模式默认使用 SQLite 作为数据库，因此 Docker 并非强制要求。但当你需要集成 PostgreSQL、测试插件与外部服务的交互，或运行端到端测试时，Docker 是必不可少的。建议在课程开始前完成 Docker 安装并确保 docker compose 可用。

2.2.4 Backstage CLI 安装

Backstage CLI 是开发 Backstage 插件和应用的核心工具链。它提供了 create-plugin、build、dev 等命令。

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

# 验证
backstage-cli --version   # 应输出 0.26.5

你也可以在项目内局部安装，但全局安装更便于快速创建新插件。安装完成后，运行 backstage-cli info 可以查看当前环境与 Backstage 模板的兼容性。

2.3 环境验证流程

完成安装后，请按以下步骤进行完整验证，确保所有工具链协同工作。

验证 Node.js 版本： node -e "console.log(process.version)"，确认 ≥ 18.17.0。
验证 Yarn 版本： yarn --version，确认为 1.22.x。
验证 Docker 运行： docker run --rm alpine echo "Docker OK"，应输出 "Docker OK"。
验证 Backstage CLI： backstage-cli --version，确认版本号。
创建临时测试项目：

# 创建一个临时目录并初始化 Backstage 应用
mkdir backstage-test && cd backstage-test
npx @backstage/create-app@latest --skip-install

# 安装依赖
yarn install

# 启动开发服务器（仅验证启动流程，可 Ctrl+C 退出）
yarn dev

如果上述步骤全部成功，说明你的开发环境已准备就绪。

2.4 环境架构示意

下图展示了本地开发环境中各工具与 Backstage 应用之间的调用关系。理解这一架构有助于后续章节中定位问题。

2.5 常见问题与排查

问题现象	可能原因	解决方案
`node --version` 显示 v16.x 或更低	系统默认 Node.js 版本未切换	运行 `nvm use 20` 并设置默认版本 `nvm alias default 20`
`yarn install` 报错 `EINTEGRITY`	Yarn 缓存损坏或网络问题	运行 `yarn cache clean` 后重试，或切换 npm 镜像源
`docker run` 提示权限被拒绝	当前用户不在 docker 用户组	运行 `sudo usermod -aG docker $USER` 并重新登录
`backstage-cli --version` 命令未找到	全局安装路径未加入 PATH	检查 npm 全局安装目录，手动添加 `export PATH=$(npm bin -g):$PATH`
`yarn dev` 启动后页面空白	端口 3000 被占用或前端构建失败	检查 `lsof -i :3000`，终止冲突进程；或运行 `yarn build` 查看具体错误

快速诊断命令：在终端中执行以下一行命令，即可输出当前环境的核心信息：

echo "Node: $(node --version) | Yarn: $(yarn --version) | Docker: $(docker --version 2>/dev/null || echo 'not found') | CLI: $(backstage-cli --version 2>/dev/null || echo 'not found')"

2.6 下一步准备

环境验证通过后，你的开发机器已经具备了运行 Backstage 应用、创建插件、调用控制平面接口的全部前置条件。在下一章中，我们将基于此环境创建第一个 Backstage 插件项目，并建立与控制平面的通信通道。

建议将本章的验证结果截图保存，作为后续排错的基准参考。