2. Backstage环境搭建：Node.js与Yarn安装、Backstage CLI初始化、本地开发环境配置

搭建稳定的本地开发环境是进行Backstage插件调试的第一步。本章将指导你完成从基础运行时安装到CLI项目初始化的全流程，确保环境基线一致，避免因工具链差异导致的调试问题。

2.1 环境依赖概览

Backstage基于Node.js生态构建，其核心依赖项及推荐版本如下表所示。请务必使用LTS（长期支持）版本，避免因运行时版本不兼容导致构建失败。

2.2 Node.js 与 Yarn 安装步骤

以下步骤适用于 macOS / Linux / Windows（WSL2）环境。推荐使用版本管理器安装，便于后续切换版本。

1. 安装 Node.js（使用 nvm）

   # 安装 nvm（Node Version Manager）
   curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
   
   # 重新加载终端配置
   source ~/.bashrc
   
   # 安装并切换到 Node.js 18 LTS
   nvm install 18
   nvm use 18
   
   # 验证版本
   node --version   # 应输出 v18.20.x 或类似
   npm --version    # 应输出 10.x

2. 安装 Yarn Classic

   # 通过 npm 全局安装 Yarn Classic
   npm install -g yarn@1.22.22
   
   # 验证版本
   yarn --version   # 应输出 1.22.22

3. 验证核心工具链

   # 检查 Git 可用性
   git --version
   
   # 检查 Yarn 是否使用正确的 Node.js 版本
   yarn node --version

2.3 Backstage CLI 初始化

Backstage 官方提供了 @backstage/create-app 脚手架工具，用于快速生成标准项目结构。初始化过程将自动创建包含核心后端、前端应用及插件目录的 monorepo 工作区。

# 使用 npx 直接运行创建命令（无需全局安装）
npx @backstage/create-app@latest --skip-install

# 在交互式提示中输入应用名称，例如：my-service-catalog
# 输入：my-service-catalog

# 进入项目目录
cd my-service-catalog

# 安装依赖（首次安装耗时较长，约 3-5 分钟）
yarn install

2.4 本地开发环境配置

初始化完成后，需要对本地开发环境进行三项关键配置：应用配置、数据库连接与插件发现路径。

2.4.1 应用配置（app-config.yaml）

编辑项目根目录下的 app-config.yaml，设置基础信息与后端代理地址：

app:
  title: 服务目录平台
  baseUrl: http://localhost:3000

backend:
  baseUrl: http://localhost:7007
  listen:
    port: 7007
  database:
    client: better-sqlite3
    connection: ':memory:'
    # 生产环境建议切换为 PostgreSQL：
    # client: pg
    # connection:
    #   host: localhost
    #   port: 5432
    #   user: backstage
    #   password: secret
    #   database: backstage

2.4.2 插件发现路径配置

在 packages/app/package.json 和 packages/backend/package.json 中，Backstage 会自动扫描 plugins/ 目录下的本地插件。如需添加新插件路径，修改 bundledPlugins 或 dynamicPlugins 配置：

// packages/backend/package.json 片段
"bundledPlugins": [
  ...require('../../plugins/my-plugin/package.json').backstage.plugin
]

2.4.3 启动开发服务器

# 同时启动前端（:3000）和后端（:7007）
yarn dev

# 或分别启动（调试插件时更常用）
# 终端1：后端
cd packages/backend
yarn start

# 终端2：前端
cd packages/app
yarn start

2.5 环境搭建流程总览

下图展示了从零开始搭建 Backstage 本地开发环境的完整流程，包含关键决策点与验证节点：

2.6 环境验证清单

完成上述步骤后，执行以下验证项，确保环境达到运行基线：