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

使用 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 LinuxWSL。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 版本当前模板为yarn4.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-applatest命令执行时你会看到类似下面的输出? 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 中定义了一组实用的选项选项说明适用场景--path [directory]指定应用存放位置默认是在当前目录下新建以应用名命名的文件夹想把应用生成到指定目录而非新文件夹时--template-path [directory]使用外部应用模板而不是内置默认模板团队维护了统一的自定义模板时--legacy使用旧版应用模板templates/legacy-app需要兼容旧版工程结构时--skip-install跳过创建后的依赖安装与构建步骤只想先拿到模板文件、稍后手动执行yarn install时使用--skip-install时命令末尾会提示你随后手动执行cd my-backstage-app yarn install1.4 脚手架背后发生了什么源码级流程当你在终端看到一行行任务清单时create-app内部正按照 createApp.ts 编排一整套流水线任务任务实现集中在 tasks.ts前置检查Prerequisites check检测 Node、Yarn、Python 版本任何硬性错误都会在交互提示之前快速失败fail fast。询问应用名通过inquirer交互收集名称或读取BACKSTAGE_APP_NAME。选择模板根据--legacy在templates/default-app与templates/legacy-app之间选择若提供了--template-path则优先使用外部模板。检查目录可用性checkAppExistsTask会确认目标目录不存在若同名目录已存在则报错提示换名见 tasks.ts。创建临时目录并渲染模板先在系统临时目录os.tmpdir()中生成内容。所有.hbs后缀文件会交给 Handlebars 编译渲染模板上下文注入应用名与默认分支等其余文件直接复制见 tasks.ts。移动到位moveAppTask将临时目录整体移动到最终位置无论成功失败都会清理临时文件。拉取 yarn.lock seedfetchYarnLockSeedTask从远端拉取一份种子锁文件写入新工程用于把有已知问题的个别依赖锁定到可用版本此过程与 create-app 包发布解耦因此失败仅产生警告而不中止见 tasks.ts。初始化 Git 仓库tryInitGitRepository检测当前不在任何 Git 仓库内时会自动执行git init、git add .与首次提交见 tasks.ts。安装依赖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 TemplatesTechDocs根 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-sqlite3connection: :memory:的内存数据库生产数据库配置在app-config.production.yaml中另行提供。integrations.githubGitHub 集成的占位配置通过token: ${GITHUB_TOKEN}引用环境变量并给出了 GitHub EnterpriseGHE的示例写法。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 startyarn 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考