Backstage CLI 命令完全指南：从 help 总览到 43 个命令的模块化实战手册

Backstage CLI 命令完全指南从 help 总览到 43 个命令的模块化实战手册【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage本指南以 Backstage CLI 的命令索引为骨架系统梳理backstage-cli提供的全部命令并结合其模块化架构逐条展开参数说明、使用示例与工作流。读完本文你将能够熟练使用new、config:*、repo/package系列生命周期命令、auth认证命令、actions动作执行命令以及迁移、国际化、补丁校验等维护工具在 Backstage 应用中完成从脚手架搭建、日常开发到版本升级的完整 CLI 操作闭环。Backstage CLI 与命令的组织方式Backstage CLI即backstage/cli包是 Backstage 项目自带的构建系统与工具链的载体。它的设计目标是为开发者提供流畅的开发体验创建新的 app 和 plugin 应当简单、迭代速度应当快、维护自定义工具的开销应当最小。在底层它使用 Webpack 做打包、Rollup 构建包、Jest 测试、ESLint 检查并提供了面向 Backstage 应用内部工作的工具如保持应用更新、校验静态配置。CLI 采用模块化架构整个命令集由一组相互独立的CLI 模块CLI Modules组成每个模块提供一组相关命令。在仓库中这些模块以独立的包存在包括packages/cli-module-auth、packages/cli-module-actions、packages/cli-module-build、packages/cli-module-config、packages/cli-module-github、packages/cli-module-info、packages/cli-module-lint、packages/cli-module-maintenance、packages/cli-module-migrate、packages/cli-module-new、packages/cli-module-test-jest、packages/cli-module-translations、packages/cli-module-package-manager-yarn等。你可以在 CLI 模块 页面了解默认模块列表与模块发现机制也可以通过 自定义默认模块 增删模块或参考 构建自己的 CLI 模块 为组织添加自定义命令。help命令总览的入口help命令用于显示命令摘要或每条命令的详细帮助屏。下面是yarn backstage-cli --help清理后的输出它展示了 CLI 全部顶层命令new [options] Open up an interactive guide to creating new things in your app auth [command] Authentication commands actions [command] Backstage action commands config:docs [options] Browse the configuration reference documentation config:print [options] Print the app configuration for the current package config:check [options] Validate that the given configuration loads and matches schema config:schema [options] Print configuration schema repo [command] Commands that run across an entire Backstage project package [command] Lifecycle scripts for individual packages migrate [command] Migration utilities versions:bump [options] Bump Backstage packages to the latest versions versions:migrate [options] Migrate plugins to the backstage-community namespace translations [command] Translation message management build-workspace workspace-dir [packages...] Builds a temporary dist workspace from the provided packages create-github-app github-org Create new GitHub App in your organization. info Show helpful information for debugging and reporting bugs help [command] display help for command可以看到命令大体分为三类单条命令如new、info、config:print、命令组如auth、repo、package、migrate、translations以及顶层工具命令如build-workspace、create-github-app。对于任意命令都可以通过yarn backstage-cli command --help查看其详细选项。以下按模块逐一展开。Auth 模块与 Backstage 实例建立受信会话Auth 模块backstage/cli-module-auth提供 CLI 与 Backstage 实例之间认证的命令。它基于OAuth 2.0 with PKCE获取访问令牌这些令牌随后会被actions等其他 CLI 命令使用。前置条件目标 Backstage 实例必须开启 CLI 认证支持。CLI 通过请求该实例 well-known 端点/api/auth/.well-known/oauth-client/cli.json来获取 OAuth 客户端元数据以确认支持。实例命名机制每个已认证的 Backstage 实例都以你选择的名字存储这个名字是引用该实例的短标签例如--instance production。登录时若不提供名字CLI 会从后端 URL 的主机名派生例如backstage.example.com。auth login启动 OAuth 授权流程自动打开浏览器完成认证并将凭据保存在本地Usage: backstage-cli auth login [options] Options: --backendUrl url Backend base URL --noBrowser Do not open browser automatically --instance name 实例的短名称用于在其他 auth 命令中引用默认取后端 URL 主机名不带任何参数运行时命令会交互式提示扫描本地app-config.yaml发现后端 URL让你选择其一或手动输入 URL并从 URL 主机派生实例名。设置--noBrowser后授权 URL 会打印到终端可手动打开。# 交互式登录 yarn backstage-cli auth login # 指定后端 URL 登录 yarn backstage-cli auth login --backendUrl https://backstage.example.com # 登录并命名实例便于后续引用 yarn backstage-cli auth login --backendUrl https://backstage.example.com --instance production # 不自动打开浏览器 yarn backstage-cli auth login --backendUrl https://backstage.example.com --noBrowserauth logout登出某个实例并清除已存凭据。命令会尽力而为地向服务器吊销 refresh token并从本地存储中移除令牌与实例元数据Usage: backstage-cli auth logout [options] Options: --instance name 要登出的实例名不提供--instance时会交互式提示从已认证实例列表中选择。yarn backstage-cli auth logout --instance production yarn backstage-cli auth logout # 交互式选择auth show显示已认证实例的详细信息包括当前用户身份与所有权实体引用ownership entity references。命令会从实例的/api/auth/v1/userinfo端点获取用户信息必要时自动刷新访问令牌Usage: backstage-cli auth show [options] Options: --instance name 要显示的实例名yarn backstage-cli auth show yarn backstage-cli auth show --instance productionauth list列出所有已认证实例默认实例以星号*标记Usage: backstage-cli auth listyarn backstage-cli auth list示例输出* production - https://backstage.example.com staging - https://backstage-staging.example.comauth print-token将访问令牌打印到标准输出若令牌已过期或即将过期则自动刷新。适合在脚本与流水线中使用Usage: backstage-cli auth print-token [options] Options: --instance name 要使用的实例名# 打印默认实例的访问令牌 yarn backstage-cli auth print-token # 在 curl 中直接使用令牌 curl -H Authorization: Bearer $(yarn backstage-cli auth print-token) \ https://backstage.example.com/api/catalog/entities # 指定命名实例 yarn backstage-cli auth print-token --instance stagingauth select选择默认实例。其他 auth 命令在未提供--instance时使用默认实例Usage: backstage-cli auth select [options] Options: --instance name 要选择的实例名不提供--instance时交互式提示选择。典型用法yarn backstage-cli auth select --instance production。认证状态存储位置认证状态保存在两处实例元数据存储在 YAML 文件~/.config/backstage-cli/auth-instances.yaml或使用 XDG 配置目录的平台对应路径包含实例名、后端 URL、令牌过期时间戳以及当前选中的实例。令牌访问令牌与刷新令牌存储在系统密钥库secret store中与 YAML 文件分离存放。Actions 模块命令行直接发现与执行 Backstage 动作Actions 模块backstage/cli-module-actions允许你在不进入 Backstage UI 的情况下从命令行发现并运行 Backstage 动作actions。Backstage 插件可暴露的动作列表参见 Well-Known Actions 文档。前置条件使用 actions 命令前必须先用auth login完成实例认证actions 命令使用已存凭据与后端通信。所有 actions 命令默认针对选中的实例运行存在多个已认证实例时用--instance指定目标。插件源Plugin Sourcesactions 模块需要知道从哪些后端插件发现动作这些插件称为插件源以元数据形式存储在已认证实例上。在使用actions list/actions execute之前需要先用actions sources系列命令管理插件源。actions list列出所有已配置插件源中的可用动作Usage: backstage-cli actions list [options] Options: --instance name 要使用的实例名默认选中实例未配置插件源时命令会提示先用actions sources add添加。yarn backstage-cli actions list yarn backstage-cli actions list --instance productionactions execute执行一个动作动作 ID 遵循pluginId:actionName格式Usage: backstage-cli actions execute [options] action-id Options: --instance name 要使用的实例名默认选中实例除了--instance标志命令还会根据动作的输入 JSON Schema 动态生成标志。Schema 中的每个属性都会变成一个 CLI 标志并自动映射类型string属性 →String标志number和integer属性 →Number标志boolean属性 →Boolean标志复杂类型对象、数组、联合类型→ 接受 JSON 输入的String标志用--help加动作 ID 可以看到该动作完整可用的标志集合及其渲染描述# 查看某动作的动态标志 yarn backstage-cli actions execute my-plugin:my-action --help # 执行动作并传参 yarn backstage-cli actions execute my-plugin:create-resource --name my-resource --count 3 # 复杂输入以 JSON 字符串传入 yarn backstage-cli actions execute my-plugin:configure --options {timeout: 30, retries: 3}actions sources 子命令Usage: backstage-cli actions sources add plugin-ids... # 添加插件源 Usage: backstage-cli actions sources list # 列出已配置插件源 Usage: backstage-cli actions sources remove plugin-ids... # 移除插件源actions sources add添加一个或多个插件源已配置的源会被跳过并给出警告。actions sources remove移除一个或多个插件源未配置的源会被跳过并给出警告。yarn backstage-cli actions sources add scaffolder yarn backstage-cli actions sources add scaffolder catalog yarn backstage-cli actions sources list yarn backstage-cli actions sources remove scaffolder catalogActions 完整工作流# 1. 登录 Backstage 实例 yarn backstage-cli auth login --backendUrl https://backstage.example.com # 2. 添加插件源以便发现动作 yarn backstage-cli actions sources add scaffolder # 3. 列出可用动作 yarn backstage-cli actions list # 4. 查看某动作的帮助含动态生成的标志 yarn backstage-cli actions execute scaffolder:create-component --help # 5. 执行动作 yarn backstage-cli actions execute scaffolder:create-component --name my-service --owner team-aBuild 模块仓库级与包级构建生命周期Build 模块backstage/cli-module-build负责 Backstage 包的构建、启动与打包既支持单包也支持整个仓库。构建系统的底层细节见 Build System。repo start启动项目中的一组包用于本地开发。若未通过参数或选项显式指定包则根据包的 package role 选择如果找到唯一的一组前端和/或后端包则启动它们存在多个匹配时优先选择packages/app和packages/backend目录若仍无匹配则回退为期望启动单个插件前端和/或后端包。所选包的package.json中start脚本内的--config选项会被读取并使用除非给本命令显式提供了--config此时以本命令为准。后端包的start脚本中的--require选项同样会被读取使用Usage: backstage-cli repo start [options] [packageNameOrPath...] Arguments: packageNameOrPath 运行指定的包而非默认包 Options: --plugin pluginId 启动仓库中任意匹配插件包的 dev 入口默认: [] --config path 要加载的配置文件替代 app-config.yaml默认: [] --inspect [host] 在 Node.js 环境启用调试器仅适用于后端包 --inspect-brk [host] 在 Node.js 环境启用调试器并在代码启动前中断仅适用于后端包 --require path 向 node 进程添加 --require 参数仅适用于后端包 --link path 链接外部工作区以解析模块repo build构建项目中所有包默认排除打包型bundled包即 role 为frontend或backend的包Usage: backstage-cli repo build [options] Options: --all 构建所有包包括打包型 app 与 backend 包 --since ref 仅构建自指定 ref 以来发生变更的包及其 dev 依赖项repo clean删除项目中所有包的缓存与输出目录Usage: backstage-cli repo clean [options]package start启动单个包用于本地开发。前端与后端开发的细节见构建系统的 bundling 一节Usage: backstage-cli package start [options] Options: --config path 要加载的配置文件替代 app-config.yaml默认: [] --role name 以显式包 role 运行命令 --check 可用时启用类型检查与 lint --require path 向 node 进程添加 --require 参数 --link path 链接外部工作区以解析模块 --entrypoint path 入口目录路径使用 index 文件或入口文件路径不含扩展名默认 dev --inspect [host] 启用 Node.js inspector可选指定 host:port --inspect-brk [host] 启用 Node.js inspector 并在用户代码启动前中断package build根据包的 role 构建单个包。构建与打包细节见 building 与 bundling 两节Usage: backstage-cli package build [options] Options: --role name 以显式包 role 运行命令 --minify 压缩生成的代码不适用于 app 包app 默认压缩 --skip-build-dependencies 跳过本地依赖的自动构建仅适用于后端包 --stats 若存在 bundle 统计信息则写入输出目录仅适用于 app 包 --config path 要加载的配置文件替代 app-config.yaml仅适用于 app 包默认: [] --module-federation 以 Module Federation remote 方式构建包仅适用于前端插件包package bundle实验性⚠️Caution实验性该命令处于实验阶段未来版本可能在不经弃用期的情况下发生破坏性变更且从主--help输出中隐藏。将插件打包为可动态加载的自包含插件包可独立部署并由 Backstage 应用动态加载同时支持后端与前端插件。与常规构建不同bundle 命令生成完全自包含的插件交付物产出 Module Federation 资源前端或将插件依赖打入插件私有node_modules先用yarn pack构建并打包本地workspace:^依赖后端仅从插件相关包生成配置 schema校验插件是否导出有效的动态加载入口仅后端。# 打包当前包输出: ./bundle/ yarn backstage-cli package bundle # 打包到指定目录输出: ../dynamic-plugins/mangled-package-name/ yarn backstage-cli package bundle --output-destination ../dynamic-plugins # 覆盖 bundle 子目录名 yarn backstage-cli package bundle --output-name my-plugin-bundle # 打包前清理输出 yarn backstage-cli package bundle --clean # 跳过插件及其本地依赖的构建 yarn backstage-cli package bundle --no-build # 跳过依赖安装与入口校验 yarn backstage-cli package bundle --no-install # 流式输出 build/pack/install 步骤的详细日志 yarn backstage-cli package bundle --verbose # 使用预构建的 dist 工作区批量打包 # 先用 backstage-cli build-workspace output-dir [packages...] --alwaysPack 创建工作区 # 再以 --pre-packed-dir 传入 yarn backstage-cli package bundle --pre-packed-dir ../dist-workspace选项汇总Options: --output-destination dir 创建 bundle 子目录的目录默认当前包目录 --output-name name bundle 子目录名输出留在包目录时默认 bundle 指定 --output-destination 时默认 mangled 包名如 myorg-plugin-foo --clean 打包前清理输出目录 --no-build 跳过包构建假定已构建 --no-install 跳过依赖安装与入口校验 --verbose 将内部步骤build、pack、install的详细输出流式打印到控制台 不加时输出被捕获到分步日志文件仅在出错时显示 --pre-packed-dir dir 预构建 dist 工作区路径来自 build-workspace --alwaysPack 跳过本地依赖打包并直接使用预打包包前端插件还会启用 yarn.lock 生成以支持 SBOM输出契约bundle 的输出是一个可独立部署的目录。消费方如backstage/backend-dynamic-feature-service或backstage/frontend-dynamic-feature-loader可以依赖以下保证所有 bundle根目录有配置了动态加载入口的package.json保留源包的backstage.role与files字段dist/目录包含构建后的插件代码存在dist/.config-schema.json当有适用 schema 时内含插件、本地工作区依赖与第三方依赖收集的 schema排除无关 Backstage 包的 schemapackage.json中不含scripts与devDependencies。后端插件backend-plugin、backend-plugin-module包含node_modules/内含全部生产依赖含本地工作区依赖版本按源 lockfile 精确固定package.json中bundleDependencies设为true。前端插件frontend-plugin、frontend-plugin-modulemain指向dist/remoteEntry.jsModule Federation remote 入口有类型声明时types指向dist/mf-types/index.d.ts不内嵌node_modules/。环境变量bundle 命令支持与 Backstage yarn 插件相同的环境变量用于解析backstage:^版本说明符BACKSTAGE_MANIFEST_FILE本地 manifest 文件路径用于离线场景、BACKSTAGE_VERSIONS_BASE_URL获取 release manifest 的自定义基础 URL。支持的包 rolebackend-plugin、backend-plugin-module、frontend-plugin、frontend-plugin-module。package clean / prepack / postpackpackage clean删除缓存目录Usage: backstage-cli package clean。package prepack应作为所有包的scripts.prepack在打包与发布时启用对package.json内字段的覆盖。细节见构建系统 publishing 一节。package postpack应作为所有包的scripts.postpack将package.json恢复到调用prepack之前的状态。build-workspace构建工作区的镜像使用每个包的打包生产版本——本质是对每个包执行yarn pack并将产物解包到目标workspace-dirUsage: backstage-cli build-workspace [options] workspace-dir [packages...] Options: --alwaysPack 强制工作区输出为对每个包执行 yarn pack 的结果警告非常慢使用--alwaysPack后输出目录可传给backstage-cli package bundle --pre-packed-dir以加速同一 monorepo 中多个插件的批量打包。Config 模块配置的查看、校验与 Schema 导出Config 模块backstage/cli-module-config提供检查、打印与校验 Backstage 配置 schema 及解析后值的命令。config:docs在浏览器中打开应用本地配置 schema 的参考文档用于查看可用的配置值、它们的作用以及被发送到何处Usage: backstage-cli config:docs [options] Options: --package name 仅包含适用于指定包的 schema -h, --help 显示命令帮助config:print打印静态配置默认读取仓库根目录的app-config.yaml使用仓库中所有本地包收集的 schema。例如验证某个配置值在构建my-app包时对前端可见yarn backstage-cli config:print --frontend --package my-appUsage: backstage-cli config:print [options] Options: --package name 仅加载适用于指定包的配置 schema --lax 不要求环境变量已设置 --frontend 仅打印前端配置 --with-secrets 在打印的配置中包含 secrets --format format 打印配置的格式json 或 yaml [yaml] --config path 要加载的配置文件替代 app-config.yaml默认: [] -h, --help 显示命令帮助config:check校验静态配置能正常加载且符合 schema默认读取仓库根目录的app-config.yaml使用仓库中所有本地包收集的 schemaUsage: backstage-cli config:check [options] Options: --package name 仅加载适用于指定包的配置 schema --lax 不要求环境变量已设置 --frontend 仅校验前端配置 --deprecated 输出已弃用的配置项 --strict 确保给定配置无错误且不包含 schema 之外的键 --config path 要加载的配置文件替代 app-config.yaml默认: [] -h, --help 显示命令帮助config:schema导出仓库中所有本地包收集的配置 schemaNote通过yarn运行时若要在命令行管道中使用输出请加 yarn 选项--silent避免非 schema 输出混入管道。Usage: backstage-cli config:schema [options] Options: --package name 仅输出适用于指定包的配置 schema --format format 打印 schema 的格式json 或 yaml [yaml] -h, --help 显示命令帮助GitHub 模块创建 GitHub AppGitHub 模块backstage/cli-module-github提供在组织内创建 GitHub App 的命令作为基于 token 的 GitHub 集成的替代方案Usage: backstage-cli create-github-app github-org命令会启动浏览器通过 GitHub 创建 App并将结果保存为可在 GitHub 集成配置中引用的 YAML 文件。它对应基于 token 的 GitHub 集成 的替代路径相关背景可参考 Backstage 认证的 GitHub Apps。Info 模块调试信息导出Info 模块backstage/cli-module-info输出关于 Backstage 环境的调试信息在提 issue 或排障时非常有用Usage: backstage-cli info [options] Options: --include patterns... 额外包含的包 glob 模式如 mycompany/backstage-* --format text|json 输出格式默认: text -h, --help 显示命令帮助输出内容涵盖系统信息、Node.js 与 npm 版本、CLI 版本及其类型在 Backstage 仓库内还是创建的 app 中、所有backstage/*包依赖版本以及任何在package.json中含backstage字段的包。命令还会区分已安装包来自 npm与本地工作区包便于理解你的 Backstage 部署结构。# 输出到控制台 yarn backstage-cli info # 额外包含匹配 glob 的包 yarn backstage-cli info --include mycompany/* # 以 JSON 输出 yarn backstage-cli info --format json # 导出 JSON 到文件以便后续处理 yarn backstage-cli info --format json backstage-info.json # 组合使用包含自定义包并导出 JSON yarn backstage-cli info --include mycompany/backstage-* --include internal/* --format json debug-info.json--format json的输出结构示例{ system: { os: Darwin 23.0.0 - darwin/arm64, node: v18.17.0, yarn: 3.6.0, cli: { version: 0.27.0, local: false }, backstage: 1.20.0 }, dependencies: { backstage/core-plugin-api: 1.8.0, backstage/plugin-catalog: 1.15.0 }, local: { mycompany/backstage-plugin-custom: 0.1.0 } }Lint 模块包级与仓库级代码检查Lint 模块backstage/cli-module-lint对单个包或整个仓库运行 lint。lint 配置细节见构建系统 linting 一节。package lint对包执行 lint。除默认eslint行为外该命令会包含 TypeScript 文件、将警告视为错误并在未列出具体文件时默认检查整个目录Usage: backstage-cli package lint [options] Options: --format format lint 报告输出格式默认: eslint-formatter-friendly --fix 自动修复违规 --max-warnings number 警告数超过该值则失败-1 允许任意数量警告默认: -1repo lint对项目中所有包执行 lintUsage: backstage-cli repo lint [options] Options: --format format lint 报告输出格式默认: eslint-formatter-friendly --since ref 仅 lint 自指定 ref 以来变更的包 --success-cache 启用成功缓存跳过上一次运行成功且未变更包的 lint --success-cache-dir path 设置成功缓存位置默认: node_modules/.cache/backstage-cli --fix 自动修复违规Maintenance 模块仓库维护与弃用跟踪Maintenance 模块backstage/cli-module-maintenance修复常见包问题并跟踪项目中的弃用项。repo fix自动修复项目中的包扫描所有包并应用针对常见问题如缺失或错误的配置的自动修复Usage: backstage-cli repo fix [options]repo list-deprecations列出项目中所有包发现的弃用项用于跟踪被弃用的 API 使用情况并规划迁移工作Usage: backstage-cli repo list-deprecations [options]Migrate 模块版本升级与包迁移工具Migrate 模块backstage/cli-module-migrate负责升级 Backstage 包版本、迁移移动过的包以及运行包迁移工具。versions:bump将全部backstage包升级到最新版本检查包注册表中的更新并在必要时更新package.json。更多配置与用法见 保持 Backstage 更新Usage: backstage-cli versions:bump [options] Options: -h, --help 显示命令帮助 --pattern glob 覆盖匹配待升级包的 glob --release version|next|main 升级到指定的 Backstage release 线或版本默认: mainversions:migrate迁移已移至backstage-community命名空间的插件。命令扫描项目中所有包的依赖找出package.json中含backstage.moved字段的依赖更新package.json中的依赖名并可选择性地重写源码中的 import 路径。改动完成后会运行yarn install更新 lockfileUsage: backstage-cli versions:migrate [options] Options: --pattern glob 覆盖匹配待升级包的 glob --skip-code-changes 跳过代码改动仅更新 package.json -h, --help 显示命令帮助其余 migrate 子命令migrate package-roles为没有backstage.role字段的包添加该字段。此字段标识每个包的用途其他 CLI 命令据此决定正确的构建与 lint 行为。migrate package-scripts按各包 role 设置脚本确保所有包都有符合其 role 的build、test、lint、prepack、postpack脚本。migrate package-exports同步包的子路径导出定义使package.json的exports字段符合各 role 的预期结构。migrate package-lint-configs将所有包迁移到使用 CLI 提供的 ESLint 配置工厂backstage/cli/config/eslint-factory替换自定义 ESLint 配置。migrate react-router-deps将所有包的react-router依赖迁移为 peer dependencies是支持更新版 React Router 的迁移工作的一部分。New 模块交互式脚手架New 模块backstage/cli-module-new提供在 Backstage 项目中创建新插件、新包及其他组件的命令Usage: backstage-cli new Options: -h, --help 显示命令帮助不带任何选项时完全交互式也可以使用--select预选创建类型用--option提供选项yarn backstage-cli new --select frontend-plugin --option pluginIdfoo该命令通常作为根package.json的脚本以yarn new执行{ scripts: { new: backstage-cli new } }new命令带有默认的插件/包集合你可以自定义该列表甚至创建自己的 CLI 模板详见 CLI Templates。Test 模块Jest 测试运行Test 模块backstage/cli-module-test-jest提供在单个包与整个仓库中运行测试的命令测试使用 CLI 内置的默认 Jest 配置。配置覆盖与编辑器支持见构建系统文档的 Jest Configuration 一节。repo test测试项目中的包。推荐将其作为项目根package.json的test脚本{ scripts: { test: backstage-cli repo test } }不带参数运行时默认在watch 模式下运行变更的测试若设置了CI环境变量则运行全部测试且不 watchyarn test提供参数时会被转发给 Jest 用于过滤要执行的测试提供完整路径则只运行这些测试yarn test packages/app/src/App.test.tsx在 CI 中想避免重复运行上次成功后未变更的测试可用--success-cache标志缓存默认存放在node_modules/.cache/backstage-cli可用--success-cache-dir path指定其他目录Usage: backstage-cli repo test [options] Options: --since ref 仅测试自指定 ref 以来变更的包 --success-cache 启用成功缓存跳过上次运行成功且未变更包的测试 --success-cache-dir path 设置成功缓存位置默认: node_modules/.cache/backstage-cli --jest-help 显示 Jest CLI 选项帮助会被透传 -h, --help 显示命令帮助package test运行测试将所有未知选项转发给 Jest默认 watch 模式。执行时process.env.NODE_ENV被设为test。命令使用 CLI 内置的默认 Jest 配置其设计目标与 monorepo 中的速度与规模相匹配以src为根目录、强制使用.test.中缀、以src/setupTests.ts作为测试 setup 位置。该配置还支持在 Yarn workspaces monorepo 根执行——自动创建一组聚合配置包含所有在test脚本中使用backstage-cli test或backstage-cli package test的包Usage: backstage-cli package test [options] Options: --backstage-cli-help 显示命令帮助Translations 模块国际化消息管理Translations 模块backstage/cli-module-translations提供导出与导入翻译消息的命令支撑 Backstage 应用的国际化工作流。更多细节见 Internationalization 文档。translations export将 app 及其所有前端插件中的翻译消息导出为 JSON 文件。必须从包目录内运行例如packages/app不能在仓库根运行。命令会发现在依赖树中的所有TranslationRef定义利用 TypeScript 类型系统提取其默认消息并连同 manifest 一起写成 JSON 文件Usage: backstage-cli translations export [options] Options: --output dir 消息与 manifest 的输出目录默认: translations --pattern pattern 消息文件相对输出目录的路径模式含 {id} 与 {lang} 占位符 默认: messages/{id}.{lang}.json -h, --help 显示命令帮助# 默认设置导出 cd packages/app yarn backstage-cli translations export # 按语言分组导出 yarn backstage-cli translations export --pattern {lang}/{id}.jsontranslations import从翻译好的 JSON 文件生成翻译资源接线wiring代码。命令读取translations export产生的 manifest 与翻译消息文件生成一个为每个已翻译 ref 创建TranslationResource对象的 TypeScript 模块。导出时使用的文件模式会存入 manifest 并由 import 命令自动复用Usage: backstage-cli translations import [options] Options: --input dir 包含 manifest 与翻译消息文件的输入目录默认: translations --output path 生成接线模块的输出路径默认: src/translations/resources.ts -h, --help 显示命令帮助cd packages/app yarn backstage-cli translations importYarn Package Manager 模块补丁引用校验Yarn package manager 模块backstage/cli-module-package-manager-yarn校验 Yarn 补丁引用、本地补丁文件与yarn.lock保持一致。当项目对 Backstage 包打补丁时它还会检查包版本是否与backstage.json中选择的 Backstage release 匹配。该命令校验 Yarn 2 及以后版本原生支持的patch:协议不检查 Yarn Classic 仓库中patch-package等工具管理的补丁。生成临时补丁的指引见 Generating temporary patches。pm verify-patches在 Yarn 仓库根运行yarn backstage-cli pm verify-patches命令扫描根与工作区package.json中的patch:引用位于resolutions、dependencies、devDependencies、optionalDependencies、peerDependencies一次性报告以下所有问题并以非零退出码结束缺失或孤立的本地补丁文件与yarn.lock不一致的补丁引用打补丁的backstage/*包缺失或与所选 Backstage release 不匹配。该命令是只读的不运行 Yarn、不安装依赖、不写项目文件。建议与yarn install --immutable搭配使用immutable 安装保护已解析的依赖状态而本命令校验补丁声明与所选 Backstage release 保持一致。对于离线或镜像环境可设置BACKSTAGE_MANIFEST_FILE指向本地 release manifest或设置BACKSTAGE_VERSIONS_BASE_URL为获取 release manifest 的基础 URL。总结按场景选择命令将全部命令按使用场景归类可以形成这样的速查视角脚手架与初始化new创建插件/包create-github-app建立 GitHub 集成migrate package-roles/package-scripts/package-exports初始化包元数据。日常开发repo start/package start启动开发环境repo test/package test运行测试package lint/repo lint检查代码。构建与发布repo build/package build构建package prepack/postpack配合发布package bundle动态加载打包build-workspace构建镜像工作区。配置管理config:docs/config:print/config:check/config:schema覆盖配置的浏览、打印、校验与 schema 导出。认证与远程操作auth login/logout/list/show/print-token/select管理实例凭据actions系列命令在命令行直接发现与执行插件动作。升级与迁移versions:bump升级版本versions:migrate迁移到backstage-communitymigrate react-router-deps适配新 React Router。质量与维护repo fix自动修复repo list-deprecations跟踪弃用pm verify-patches校验补丁与 release 对齐info导出排障所需的完整环境信息。无论是新入门的开发者还是维护大型 monorepo 的团队都可以把本文当作 Backstage CLI 的命令速查手册在实际操作中随时查阅对应模块的详细选项与示例。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考