企业官网建设流程全解析

使用 @backstage/create-app 从零脚手架创建 Backstage 开发者门户应用

【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage

导读

本文是 Backstage 四条 Golden Path（黄金路径）系列指南的第一篇，完整讲解如何通过@backstage/create-app脚手架工具在本地生成一个可运行的 Backstage 开发者门户应用。读完本文，你将掌握从环境准备、交互式创建、CLI 选项使用，到理解生成工程结构与关键配置、并在本地启动开发的完整实战能力。

摘要：这篇指南能做什么

本指南的目标读者是开发者与管理员。它会带领你一步步创建属于自己的、可定制的 Backstage 应用，这也是评估 Backstage、在其上做二次开发或进行演示的第一步。

完成本指南后，你将拥有一个独立、本地可运行的 Backstage 安装实例，内置 SQLite 数据库与演示（demo）数据。

⚠️明确边界（非生产就绪）需要特别说明：这样生成的并非生产环境就绪的安装，其中也不包含与你的组织相关的任何特定信息。如何在后续步骤中将 Backstage 定制为贴合你自身业务场景的形态，正是整个 Golden Path 系列后续内容要解决的问题。若你更关心如何让团队的开发者门户落地，也可以直接跳到adoption（采纳）路线。

环境准备（Prerequisites）

本指南假设你具备在 Unix/Linux 类操作系统上使用终端的经验，并熟悉npm、yarn这两个包管理器命令。开始之前，请确认以下环境项均已就绪：

• Unix 系操作系统：Linux、macOS，或 Windows Subsystem for Linux（WSL）。
• GNU 风格的构建环境：脚手架过程中部分原生依赖需要编译。Debian/Ubuntu 上建议安装make与build-essential包；macOS 上执行xcode-select --install安装 Xcode 命令行构建工具。
• 具备安装依赖所需的提升权限账户。
• 已安装curl或wget。
• Node.js Active LTS 版本，安装方式任选其一：nvm（推荐）、官方二进制包、系统包管理器或 NodeSource 软件源。
• Yarn：启用corepack后安装 Backstage 所要求的 Yarn 版本。
• Git。

关于 Node 与 Yarn 版本的实际要求（以仓库源码为准）

不同的文档版本对版本号有不同的表述，这里以当前仓库源码为准给出精确信息：

• Node.js 必须是偶数号的 LTS 版本。在 createApp.ts 中明确声明了受支持的版本集合SUPPORTED_NODE_VERSIONS = ['22.x', '24.x']，且该列表与根package.json的engines.node字段保持同步。脚手架启动时会先做前置校验：奇数号版本（如 21、23）会被直接判定为不支持的 LTS 并终止；版本不在支持列表内同样会报错（见 createApp.ts）。
• Yarn 通过 Corepack 管理：生成的工程根package.json.hbs中packageManager字段声明了具体 Yarn 版本（当前模板为yarn@4.13.0，见 package.json.hbs）。历史文档曾以yarn set version 4.4.1为例，实际以你所创建应用模板声明的版本为准。前置校验中，若yarn命令不可用，创建过程会直接失败（见 createApp.ts）。
• Python 为软依赖：若检测不到python3/python，脚手架只会给出黄色警告（node-gyp 编译部分原生依赖时需要它），并不会中止流程（见 createApp.ts）。

第一步：脚手架你的 Backstage 应用

1.1 运行交互式创建命令

创建新应用需要运行一条交互式命令。执行前，先在终端中切换到你希望创建新目录的位置（一个你感到舒适、方便放置新工程的工作目录）。

该命令的向导（wizard）会询问你为新应用取的名字，这个名字同时会作为为你创建的文件夹名称。

运行命令如下：

npx @backstage/create-app@latest

命令执行时，你会看到类似下面的输出：

? Enter a name for the app [required] my-backstage-app Creating the app... Checking if the directory is available: checking my-backstage-app ✔ Creating a temporary app directory: Preparing files: copying .dockerignore ✔ copying .eslintignore ✔ templating .eslintrc.js.hbs ✔ ... Moving to final location: moving my-backstage-app ✔ fetching yarn.lock seed ✔ Installing dependencies: executing yarn install ✔ executing yarn tsc ✔ Successfully created my-backstage-app

整个安装过程可能需要几分钟。如果看到加载动画长时间旋转不停，不必焦虑——后台正在进行大量工作（完整依赖安装 + TypeScript 编译）。

1.2 应用名称的校验规则

交互式输入名称时，底层使用inquirer做了严格校验（见 createApp.ts）：

• 名称必填，不能为空；
• 必须匹配正则/^[a-z0-9]+(-[a-z0-9]+)*$/，即只能是小写字母、数字和连字符（-），且连字符不能出现在开头或结尾，也不能连续出现。
• 如果你不想交互输入，可以通过环境变量BACKSTAGE_APP_NAME直接指定应用名，从而跳过向导提问。

1.3 create-app CLI 的完整选项

@backstage/create-app不仅仅是一条无参数命令。在其命令行入口 index.ts 中定义了一组实用的选项：

使用--skip-install时，命令末尾会提示你随后手动执行：

cd my-backstage-app && yarn install

1.4 脚手架背后发生了什么（源码级流程）

当你在终端看到一行行任务清单时，create-app内部正按照 createApp.ts 编排一整套流水线任务（任务实现集中在 tasks.ts）：

1. 前置检查（Prerequisites check）：检测 Node、Yarn、Python 版本，任何硬性错误都会在交互提示之前快速失败（fail fast）。
2. 询问应用名：通过inquirer交互收集名称（或读取BACKSTAGE_APP_NAME）。
3. 选择模板：根据--legacy在templates/default-app与templates/legacy-app之间选择；若提供了--template-path则优先使用外部模板。
4. 检查目录可用性：checkAppExistsTask会确认目标目录不存在，若同名目录已存在则报错提示换名（见 tasks.ts）。
5. 创建临时目录并渲染模板：先在系统临时目录（os.tmpdir()）中生成内容。所有.hbs后缀文件会交给 Handlebars 编译渲染（模板上下文注入应用名与默认分支等），其余文件直接复制（见 tasks.ts）。
6. 移动到位：moveAppTask将临时目录整体移动到最终位置，无论成功失败都会清理临时文件。
7. 拉取 yarn.lock seed：fetchYarnLockSeedTask从远端拉取一份种子锁文件写入新工程，用于把有已知问题的个别依赖锁定到可用版本；此过程与 create-app 包发布解耦，因此失败仅产生警告而不中止（见 tasks.ts）。
8. 初始化 Git 仓库：tryInitGitRepository检测当前不在任何 Git 仓库内时，会自动执行git init、git add .与首次提交（见 tasks.ts）。
9. 安装依赖：buildAppTask依次执行yarn install与yarn tsc；若安装超过 10 分钟会提示你可用 Ctrl-C 退出后手动执行这两条命令（见 tasks.ts）。

上述各选项与任务之间的编排关系，可以进一步参考其单元测试 createApp.test.ts：它验证了默认路径、--path、--legacy、--template-path等分支分别触发对应的任务组合。

1.5 版本注入机制：模板如何保持与发布同步

生成应用时，package.json中所有@backstage/*依赖的版本号并不是写死的。在 versions.ts 中维护了一张完整的版本映射表，每次 Backstage 发版都会保证该包同步升级，因此模板总是能引用到最新的配套包版本。这条机制保证了"脚手架出来的应用天然与当前 Backstage 版本对齐"。

生成的应用结构

脚手架完成后，你会得到一个包含示例数据的可用 Backstage 应用。下面是生成工程的简化目录布局：

app ├── app-config.yaml ├── catalog-info.yaml ├── package.json └── packages ├── app └── backend

各部分的职责如下：

• app-config.yaml：应用的主配置文件。前端、后端、认证、软件目录、TechDocs、权限等几乎所有核心功能的配置都从这里读取。更完整的说明见 配置文档。
• catalog-info.yaml：软件目录实体（Catalog Entities）描述符文件，用来描述你自己的组件/系统/API 等实体，让 Backstage 的软件目录认识它们。格式说明见 软件目录描述符格式（仓库内相关介绍见 descriptor-format 目录）。
• package.json：工程根级 package.json。注意：不要在这里添加 npm 依赖——新依赖应安装到对应的 workspace 包中，而不是根目录。
• packages/：Lerna 叶子包（leaf packages）/ workspace 集合。这里的每个子目录都是一个独立包，由 Lerna/Yarn workspaces 统一管理。
• packages/app/：一个功能完整的前端 Backstage 应用，是了解 Backstage 的绝佳起点（React 应用，内含丰富的插件友好默认配置）。
• packages/backend/：后端应用，为以下能力提供支撑（更多细节见各自文档）：
  • 认证 Authentication
  • 软件目录 Software Catalog
  • 软件模板 Software Templates
  • TechDocs

根 package.json 的关键细节

从模板 package.json.hbs 可以看到一些值得留意的工程约定：

• engines.node声明"node": "22 || 24"，与 create-app 的前置校验一致；
• workspaces覆盖packages/*与plugins/*——这也是为什么新增插件/包时它们能自动纳入统一管理；
• 常用脚本由@backstage/cli提供：yarn start（本地开发）、yarn build:all（全量构建）、yarn test、yarn lint、yarn new（用backstage-cli new交互式生成新插件/模块）等。

开箱即用的示例数据

模板在examples/下预置了演示内容：entities.yaml（示例组件/系统/API/资源实体）、org.yaml（示例用户与组）、以及一个示例软件模板template/template.yaml。主配置 app-config.yaml.hbs 中的catalog.locations会把它们自动加载进软件目录，所以你首次打开应用就能看到示例数据。

生成的 app-config.yaml 关键配置解读

脚手架生成的app-config.yaml是理解 Backstage 配置体系的入口。下面结合模板 app-config.yaml.hbs 解读几个核心段落：

• app：应用标题与baseUrl（默认http://localhost:3000），以及前端扩展（extensions）的挂载配置——默认将 catalog 页面挂载到根路径/，并预置了 Home 页的组件布局（搜索栏、收藏实体、随机笑话、快捷工具、世界时钟、访问统计等 widget）。
• backend：后端baseUrl（默认http://localhost:7007）、监听端口、CSP 与 CORS 策略（origin: http://localhost:3000）、以及数据库配置。本地开发默认使用better-sqlite3+connection: ':memory:'的内存数据库；生产数据库配置在app-config.production.yaml中另行提供。
• integrations.github：GitHub 集成的占位配置，通过token: ${GITHUB_TOKEN}引用环境变量，并给出了 GitHub Enterprise（GHE）的示例写法。
• auth.providers：默认启用guest: {}访客登录，方便零配置体验；正式接入企业身份源时替换/追加对应 provider 即可。
• catalog：导入规则（entityFilename: catalog-info.yaml）、允许的实体类型（rules）、以及本地示例数据的位置加载。
• techdocs：默认builder: 'local'、生成器runIn: 'docker'、发布器type: 'local'，并注释说明了生产环境迁移到外部存储的方向。
• permission.enabled: true：权限框架默认开启。

这些配置项在正式部署前都需要按你的组织情况调整——这正是 Golden Path 后续内容（认证、部署、采纳）要深入的部分。

本地运行你的 Backstage 应用

脚手架完成后，进入应用目录并启动开发模式：

cd my-backstage-app # 替换为你的应用名 yarn start

yarn start会在同一个终端窗口中以前台两个进程（标记为[0]与[1]）的方式同时启动前端与后端。前端编译完成后，浏览器会自动打开你的门户；若浏览器没有自动弹出，当看到webpack compiled successfully（当前版本为Rspack compiled successfully）提示时，直接访问 http://localhost:3000 即可。

启动输出大致如下图所示：

启动完成后你将看到如下门户界面：

本地开发架构要点

本地开发模式下，yarn start实际管理着两个进程：

• 前端（packages/app）：默认监听3000端口，是一个带插件友好默认配置的 React 应用。本地开发使用 rspack 做快速编译，提供近乎即时的反馈；保存 React 源码后稍等片刻即可看到Rspack compiled successfully。
• 后端（packages/backend）：默认监听7007端口，是一个 Node.js 应用，内部通过 Express 提供 HTTP 服务并连接数据库。
• 数据库：本地使用 SQLite（内存模式）。它快速且适合本地开发，但具有临时性（ephemeral）——不应依赖它在多次yarn start之间保留数据；不过热重载期间数据是保持的。
• 热重载（Hot Reload）：前后端均支持。前端保存文件触发重编译；后端修改后会出现Change detected, restarting the development server...提示并重启。

注：以上仅涉及本地开发形态；Golden Path 的deployment（部署）路线会专门讲解生产架构。

常见问题

• 应用没有运行在预期端口上？Backstage 默认前端端口为3000、后端端口为7007。请确认相关命令没有以错误状态退出；对于远程或容器化环境，还要确保上述端口可达（如已配置端口映射/防火墙放行）。

下一步：继续 Golden Path 之旅

现在你已经拥有了一个脚手架完成的应用，接下来自然是学习如何在本地启动并开发它——详见 本地开发指南。

本次创建的create-appGolden Path 是四条黄金路径中的第一条（另三条分别为插件开发、生产部署、门户采纳推广），建议在 100% 完成本指南后再继续后续路线（adoption采纳路线是例外，可先行阅读）。相关源码与模板可进一步参考 packages/create-app 目录，其中 README 还说明了本地克隆仓库后通过yarn backstage-create-app运行的方式。

【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage