📚 课程目录第2章开发环境搭建

2. 开发环境搭建：Node.js 与 Yarn 安装、Backstage CLI 工具、创建 Backstage 应用项目

搭建稳定、可复现的开发环境是 Backstage 插件开发的基石。本章将引导你完成从基础运行时安装到项目脚手架初始化的全流程，确保后续章节的示例代码能够在统一的环境中正确运行。

2.1 环境依赖概览

Backstage 应用本质上是基于 Node.js 的 monorepo 项目，依赖以下核心运行时与包管理器：

组件	推荐版本	说明
Node.js	18.x LTS 或 20.x LTS	Backstage 1.x 要求 Node.js ≥ 18；推荐使用 LTS 版本以获得长期支持
Yarn	1.22.x (Classic) 或 3.x (Berry)	Backstage 官方使用 Yarn Classic；Yarn Berry 需额外配置 nodeLinker
Git	≥ 2.30	用于版本管理和模板初始化时的仓库克隆
Docker (可选)	≥ 20.10	本地运行 PostgreSQL 或测试容器化部署时使用

版本对齐建议： 如果你同时维护多个 Node.js 项目，强烈建议使用 nvm（Node Version Manager）管理 Node.js 版本。Backstage 对 Node.js 版本敏感，使用错误的版本可能导致 node-gyp 编译失败或依赖安装异常。

2.2 Node.js 与 Yarn 安装

2.2.1 安装 Node.js

推荐通过 nvm 安装 Node.js 18 LTS：

# 安装 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 alias default 18

# 验证版本
node --version   # 应输出 v18.20.x 或类似
npm --version    # 应输出 10.x

Windows 用户注意： nvm 官方不支持 Windows。请使用 nvm-windows（https://github.com/coreybutler/nvm-windows）或直接下载 Node.js 18 LTS 安装包。安装后务必重启终端，确保 node 和 npm 命令可用。

2.2.2 安装 Yarn Classic

Backstage 官方模板默认使用 Yarn Classic（v1.x）。全局安装命令如下：

# 使用 npm 全局安装 Yarn
npm install -g yarn

# 验证版本
yarn --version   # 应输出 1.22.x

如果你希望使用 Yarn Berry（v3.x），需要在创建项目后额外配置 .yarnrc.yml 文件，设置 nodeLinker: "node-modules" 以兼容 Backstage 的 monorepo 结构。

2.3 Backstage CLI 工具

Backstage 提供了一套命令行工具 @backstage/cli，用于项目创建、插件脚手架生成、构建与测试。它封装了 Webpack、Jest、ESLint 等工具的配置，让开发者专注于业务逻辑。

2.3.1 核心命令速查

命令	功能	使用场景
`yarn create app`	创建新的 Backstage 应用项目	初始化整个服务目录平台
`yarn new --select plugin`	生成插件脚手架	快速创建插件目录结构与模板代码
`yarn dev`	启动开发服务器（前端 + 后端）	本地开发与调试
`yarn build`	构建生产版本	部署前的打包
`yarn test`	运行测试套件	单元测试与集成测试
`yarn backstage-cli versions:check`	检查依赖版本一致性	升级 Backstage 版本后校验

2.3.2 CLI 工具的内部工作流程

下图展示了 yarn create app 命令从执行到项目生成的核心流程：

  关键理解： Backstage CLI 并非一个独立的二进制文件，而是通过 @backstage/create-app 包提供的交互式脚手架。执行 yarn create app 时，Yarn 会自动从 npm registry 下载该包并执行其入口脚本。

2.4 创建 Backstage 应用项目

2.4.1 使用官方模板初始化

确保 Node.js 和 Yarn 安装正确后，执行以下命令创建新的 Backstage 应用：

# 创建应用（替换 my-backstage 为你的项目名称）
yarn create app my-backstage

# 进入项目目录
cd my-backstage

# 启动开发服务器
yarn dev

在交互式问答中，CLI 会询问以下信息：

应用名称： 默认使用你传入的目录名，如 my-backstage。
是否使用 PostgreSQL： 如果选择 Yes，需要本地运行 PostgreSQL 实例；选择 No 则使用 SQLite 作为默认数据库，适合快速开发。
是否包含示例数据： 建议选择 Yes，以便在开发阶段看到预置的服务目录数据。

首次启动耗时说明： yarn dev 会并行启动前端（默认端口 3000）和后端（默认端口 7007）。首次启动需要编译所有依赖，耗时约 2-5 分钟，具体取决于网络速度和机器性能。后续启动会利用缓存，速度显著提升。

2.4.2 项目目录结构解析

创建成功后，项目根目录结构如下：

my-backstage/
├── app-config.yaml          # 应用配置文件（数据库、集成、插件配置）
├── catalog-info.yaml        # 服务目录实体定义（默认包含示例组件）
├── packages/
│   ├── app/                 # 前端应用（React + Material UI）
│   │   ├── src/
│   │   │   ├── App.tsx      # 前端根组件
│   │   │   └── ...
│   │   └── package.json
│   └── backend/             # 后端应用（Express + 插件后端）
│       ├── src/
│       │   ├── index.ts     # 后端入口
│       │   └── plugins/     # 后端插件目录
│       └── package.json
├── plugins/                 # 自定义插件目录（初始为空）
├── yarn.lock                # 依赖锁定文件
└── package.json             # 根 monorepo 配置（workspaces）

2.4.3 验证安装成功

启动后，在浏览器中访问 http://localhost:3000，应看到 Backstage 的默认首页，包含左侧导航栏和示例服务目录数据。如果页面正常渲染，说明开发环境搭建成功。

2.5 常见问题与排查

问题现象	可能原因	解决方案
`yarn create app` 卡住或报错	npm registry 访问慢或网络代理问题	设置 npm 镜像源：`npm config set registry https://registry.npmmirror.com`
启动后前端白屏，控制台报 CORS 错误	后端未正确启动或端口冲突	检查 `app-config.yaml` 中的 `backend.baseUrl` 配置；确保 7007 端口未被占用
`node-gyp` 编译失败	缺少 C++ 编译工具链	macOS 安装 Xcode Command Line Tools；Windows 安装 `windows-build-tools`
Yarn Berry 报 `YN0002` 错误	nodeLinker 配置不兼容	在 `.yarnrc.yml` 中添加 `nodeLinker: "node-modules"`

性能提示： 在后续开发中，频繁执行 yarn install 会消耗大量时间。建议在 package.json 的 scripts 中添加 "postinstall": "yarn backstage-cli versions:check"，在安装后自动检查依赖一致性，避免因版本不匹配导致的运行时错误。

2.6 开发环境架构总览

下图展示了搭建完成后，本地开发环境的组件关系与数据流向：