2. 搭建第一个Backstage应用

Backstage 是 Spotify 开源的一套开发者门户框架，它本身不是一个开箱即用的成品，而是一个由前端应用、后端服务、插件体系和配置系统共同组成的工程骨架。搭建第一个 Backstage 应用，核心任务不是写业务代码，而是理解脚手架生成了什么、这些包之间如何协作、本地如何启动，以及后续如何管理版本。本节围绕 create-app 脚手架展开，带你完成从初始化到本地运行、再到目录结构解析的完整闭环。

一、使用 create-app 初始化项目

Backstage 官方推荐使用 @backstage/create-app 脚手架创建项目。它会在指定目录下生成一个完整的 monorepo 工程，包含前端、后端、插件、配置和工具链。执行命令前，请确保 Node.js 版本满足要求（Backstage 通常要求 Node 18 或 20 的 LTS 版本），并准备好 yarn 或 npm 作为包管理器。

npx @backstage/create-app@latest
# 交互式输入应用名称，例如 my-portal
# 脚手架会创建 ./my-portal 目录并安装依赖
cd my-portal
yarn install

脚手架执行过程中会询问应用名称，随后自动生成目录并安装依赖。安装完成后，项目根目录会出现 package.json、yarn.lock、app-config.yaml、packages/、plugins/ 等关键文件与目录。此时不要急于修改代码，先通过本地启动确认骨架可用。

二、前端与后端包结构

Backstage 采用 monorepo 组织方式，前端和后端是两个独立的包，分别位于 packages/app 和 packages/backend。前端包负责渲染用户界面、路由和插件页面；后端包负责提供 API、认证、插件后端逻辑和数据库访问。两者通过 app-config.yaml 中的配置项连接，前端在运行时读取配置，后端在启动时加载配置。

前端包的核心入口是 packages/app/src/App.tsx，其中定义了路由、插件挂载点和整体布局。后端包的核心入口是 packages/backend/src/index.ts，其中注册了后端插件、数据库客户端和认证策略。插件目录 plugins/ 用于存放自定义插件，每个插件通常也分为前端和后端两部分。理解这三层结构，是后续扩展门户功能的基础。

三、本地启动与热重载

Backstage 的本地开发体验依赖两个命令：yarn start 和 yarn start-backend。前者启动前端开发服务器，默认监听 3000 端口；后者启动后端服务，默认监听 7007 端口。前端通过代理将 /api 请求转发到后端，因此你只需要访问 http://localhost:3000 即可看到门户界面。

# 终端 1：启动前端
yarn start

# 终端 2：启动后端
yarn start-backend

# 浏览器访问 http://localhost:3000

热重载是 Backstage 开发效率的关键。前端使用 webpack-dev-server，修改 packages/app/src 下的文件后，浏览器会自动刷新或局部更新；后端使用 nodemon 监听 packages/backend/src，修改后自动重启服务。需要注意的是，修改 app-config.yaml 后通常需要重启后端才能生效，因为配置在启动时被加载。若前端页面出现空白或接口 404，优先检查后端是否已启动、代理配置是否正确。

四、目录结构解析

一个典型的 Backstage 项目根目录包含以下关键内容：

• packages/app：前端应用包，包含 src/App.tsx、src/index.tsx 和 package.json。
• packages/backend：后端应用包，包含 src/index.ts 和 package.json。
• plugins/：自定义插件目录，每个插件是一个独立的工作区包。
• app-config.yaml：主配置文件，定义应用标题、后端地址、插件配置和集成信息。
• app-config.local.yaml：本地覆盖配置，通常不提交到版本库，用于存放个人令牌或本地数据库连接。
• package.json：根工作区配置，定义脚本、依赖和 workspaces 字段。
• yarn.lock：锁定依赖版本，保证团队环境一致。

理解目录结构后，你可以快速定位修改点：改界面去 packages/app/src，改接口去 packages/backend/src，加功能去 plugins/，调配置去 app-config.yaml。这种清晰的职责划分，是 Backstage 能够支撑大型开发者门户的重要原因。

五、版本管理策略

Backstage 的版本管理需要同时关注框架版本和项目自身版本。框架版本由 package.json 中的 @backstage/* 依赖决定，建议使用 yarn backstage-cli versions:bump 命令统一升级，避免手动修改导致依赖冲突。项目自身版本则通过 Git 分支和标签管理，推荐采用主干开发加发布分支的策略。

在实际团队协作中，建议将 app-config.local.yaml 加入 .gitignore，避免个人令牌泄露；将 yarn.lock 提交到版本库，保证依赖可复现；升级 Backstage 版本时，先在独立分支执行 versions:bump，运行 yarn test 和 yarn tsc 验证，再合并到主干。对于插件版本，尽量保持与主框架版本一致，减少兼容性问题。

完成以上步骤后，你已经拥有了一个可运行、可修改、可扩展的 Backstage 应用骨架。下一步的重点不是继续堆功能，而是理解插件如何注册、配置如何分层、前后端如何通过 API 契约协作。这些能力将决定你的开发者门户能否从“能跑”走向“好用”。