企业官网建设流程全解析

Backstage v1.19.0 版本深度解析：新后端启动命令转正、声明式前端集成持续演进

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

本指南基于 docs/releases/v1.19.0-changelog.md 编写。Backstage 是一个用于构建开发者门户（Developer Portal）的开源框架，v1.19.0 是其在「新后端系统（new backend system）」与「声明式前端集成（declarative integration）」两条主线上取得关键进展的版本：EXPERIMENTAL_BACKEND_START启动方式正式转正为默认行为，前端frontend-plugin-api/frontend-app-api的 API 形态进一步收敛，同时 TechDocs、Scaffolder、Catalog、Auth、Kubernetes 等多个插件迎来功能性增强。读完本文，你将掌握 v1.19.0 的全部破坏性变更、迁移路径与关键新能力，并能对照仓库源码验证其底层实现。

一、@backstage/cli@0.23.0：新后端start命令成为默认

这是 v1.19.0 中最具里程碑意义的变化。

1.1 环境变量开关翻转：EXPERIMENTAL_BACKEND_START→ 默认 →LEGACY_BACKEND_START

此前通过设置EXPERIMENTAL_BACKEND_START开启的新后端start命令，在本版本中正式成为默认行为。如果你尚未迁移到新后端系统，官方给出的回退方式是设置LEGACY_BACKEND_START环境变量：

# 使用新后端 start 命令（v1.19.0 起为默认） yarn start-backend # 尚未迁移到新后端系统时，回退到旧行为 LEGACY_BACKEND_START=1 yarn start-backend

在仓库的 packages/cli/CHANGELOG.md 中可以确认这一变更（提交7077dbf131），也可以看到后续版本中该标志逐步被标记为 deprecated 并最终移除的完整生命周期。升级提示：如果你还在使用旧的 Webpack 构建方式启动后端，建议在升级到 v1.19.0 之前优先完成新后端系统的迁移，而不是长期依赖LEGACY_BACKEND_START。

1.2 底层机制：从 Webpack 到 Node.js Loaders

新命令在实现机制上有根本性改变：

• 不再基于 Webpack，而是使用 Node.js 的 loader 机制在运行时即时转译（transpile on the fly）TypeScript 与模块代码；
• 不再做模块级热重载（hot reload），而是在代码变更时重启整个后端进程；
• 为了不让重启影响开发体验，SQLite 数据库状态通过一个父进程得以跨重启保持。

这一设计变化带来的好处是启动链路更轻量、与 Node.js 生态更贴近，代价则是抛弃了 Webpack 的模块热替换能力。本版本还修复了多个与它相关的细节问题：Windows 下的运行支持（68158034e8）、Windows 下无法优雅关闭后端进程（d0f26cfa4f）、以及递归监听导致的重复重启（425203f898，起因是误监听了无关文件）。

1.3 配套工程化变更

@backstage/cli@0.23.0还包含一批影响日常开发的变更：

• typescript-eslint 升级到 6.7.x（8defbd5434）：更新@typescript-eslint/eslint-plugin至6.7.5，新增对TypeScript 5.2的兼容；
• React 18 环境标记（9468a67b92）：前端构建与测试中，若存在react-dom/client（即使用 React 18），会定义process.env.HAS_REACT_DOM_CLIENT，从而支持对react-dom/client的条件导入；
• yarn new新增node-library模板（21cd3b1b24），方便快速创建 Node 库包；
• CJS 构建显式设置exports: 'named'（3ef18f8c06），保证如exports["default"] = catalogPlugin;这样的具名导出形态；
• scaffolder 模块模板推荐用createMockDirectory替代mock-fs（b9ec93430e）；
• 实验性包发现机制改为始终以包名（而非完整模块 id）做 include/exclude 过滤，指向 subpath 导出的条目改用新增的export字段描述子路径（7187f2953e）。

1.4.icon.svg扩展废弃与迁移示例

CLI 对.icon.svg文件扩展的支持已被废弃并计划移除（2ef6522552）。原因是该扩展的实现与特定版本的 MUI 和 SVGO 绑定过深，阻碍了构建系统的演进。官方给出的迁移方式是：将.icon.svg文件重命名为.tsx，把<svg>元素替换为 MUI 的<SvgIcon>并补充必要导入：

import React from 'react'; import SvgIcon from '@material-ui/core/SvgIcon'; import { IconComponent } from '@backstage/core-plugin-api'; export const CodeSceneIcon = (props: SvgIconProps) => ( <SvgIcon {...props}> <g> <path d="..." /> </g> </SvgIcon> );

本版本中已有多个插件（如 codescene、graphiql、ilert）完成内部重构，绕开了该废弃扩展（9c9a9100b0）。未来 Backstage 可能通过配置方式为内部插件重新引入此类能力，但当前阶段必须迁移。

二、前端声明式集成系统：frontend-app-api/frontend-plugin-api@0.2.0

v1.19.0 对「下一代前端系统」（基于扩展 extension 的声明式集成）做了大量 API 收敛，这些变化全部是Minor（含破坏性）级别，值得正在体验 alpha 集成能力的开发者重点关注。

2.1 扩展挂载点语法重构：at→attachTo

frontend-plugin-api@0.2.0将扩展的挂载点配置从at: 'id/input'改为结构化对象（06432f900c）：

// 旧写法 createExtension({ at: 'app/router', }) // v1.19.0 新写法 createExtension({ attachTo: { id: 'app/router', input: 'default' }, })

同时，前端应用会拒绝挂载到不存在 input 的扩展（68ffb9e67d），并阻止 root 扩展被覆盖以及插件扩展重复注册（66d51a4827）。

2.2createApp选项重塑

frontend-app-api@0.2.0对createApp的参数进行了系统性调整（9d03dfe5e3、d920b8c343、2ecd33618a）：

配套能力还包括：

• 主题可配置化：新增createThemeExtension与coreExtensionData.theme（52366db5b3），默认主题改为通过扩展实现，开发者可通过扩展覆盖主题；
• 扩展覆盖机制：createExtensionOverrides用于安装一组会替换现有扩展的扩展集合（c1e9ca6500）；
• 路由系统兼容：新增对既有路由系统的支持（1718ec75b7），同时移除了对新增useRouteRef的支持（4461d87d5a），并修复子路由无法匹配的问题（1e60a9c3a5）；
• 可观测性：为扩展实例实现toString()与toJSON()（5072824817），便于调试与序列化；
• 运行时包过滤：对已发现包的过滤条件现在也在运行时生效，可通过app.experimental.packages配置在运行时禁用包（f78ac58f88）；
• 隐藏的'root'扩展移除：改为作为'core'扩展的 input，校验逻辑同步迁移（d7c5d80c57）。

2.3 各插件的/alpha实验性集成

本轮版本中，大量插件开始提供/alpha子路径下的声明式集成入口，包括：

• plugin-catalog：CatalogSearchResultItemExtension、Catalog API 迁移至声明式集成（e5a2956dd2）；
• plugin-techdocs：TechDocs 声明式集成（27740caa2d）与TechDocsSearchResultItemExtension；
• plugin-search：兼容声明式集成系统的实验性 search 插件，以及createSearchResultListItemalpha 版本；
• plugin-adr/plugin-explore：各自的*SearchResultItemExtension；
• plugin-user-settings、plugin-tech-radar：实验性声明式集成支持；
• frontend-plugin-api：Sidebar item 扩展新增SidebarGroup支持（d3a37f55c0），插件创建时可分配routes与externalRoutes（2ecd33618a）。

三、实验性插件配置 API 移除：迁移到国际化（i18n）方案

core-plugin-api@1.7.0移除了实验性插件配置 API（322bbcae24）：

• 插件选项中的__experimentalReconfigure()
• 插件实例上的__experimentalConfigure()方法

plugin-catalog@1.14.0同步去掉了对实验性重配置 API 的实现，创建按钮标题改由实验性国际化 API 配置，通过/alpha导出的catalogTranslationRef实现：

import { catalogTranslationRef } from '@backstage/plugin-catalog/alpha'; const app = createApp({ __experimentalTranslations: { resources: [ createTranslationMessages({ ref: catalogTranslationRef, catalog_page_create_button_title: 'Create Software', }), ], }, });

类似的迁移也出现在 cost-insights 插件中（959aa2a09f）：趋势线隐藏改为通过配置costInsights.hideTrendLine = true实现。test-utils同步移除了 alpha 的MockPluginProvider导出（322bbcae24）。

四、TechDocs：mkdocs 配置文件名可自定义 + 自定义 preparer 目录清理

4.1serve命令新增--mkdocs-config-file-name

此前techdocs-cli serve只能识别名为mkdocs.yaml/mkdocs.yml的配置文件。v1.19.0 为serve命令新增了--mkdocs-config-file-name参数（d06b30b050，同时作用于@techdocs/cli与plugin-techdocs-node）：

yarn techdocs-cli serve --mkdocs-config-file-name site-config.yml

仓库源码可以完整验证这条链路：

• 参数定义位于 packages/techdocs-cli/src/commands/index.ts：'-c, --mkdocs-config-file-name <FILENAME>'；
• packages/techdocs-cli/src/commands/serve/serve.ts 将其透传给getMkdocsYml解析配置路径；
• 底层 packages/techdocs-cli/src/lib/mkdocsServer.ts 中的runMkdocsServer会把该值转换为 mkdocs 自身的--config-file参数，在 Docker 模式（第 58-60 行）与本地模式（第 79-81 行）下都会生效。

4.2 自定义 preparer 的shouldCleanPreparedDirectory

plugin-techdocs-backend@1.8.0与plugin-techdocs-node@1.9.0允许自定义 preparer 控制 prepared 目录的清理（344cfbcfbc）。使用自定义 preparer 时，preparedDir可能长期占用磁盘空间，因此所有自定义 preparer 需要实现新的shouldCleanPreparedDirectory方法，声明在文档生成后是否应清理该目录。

4.3 React 18 支持与体验优化

plugin-techdocs@1.8.0增加了 React 18 支持：若存在react-dom/client，将使用新的createRootAPI（9468a67b92）。同时DocsTable的分页控件改为按需动态显示（3605370af6），并默认在 TechDocs 表中加入 kind 列（df449a7a31）。

五、Scaffolder：publish:gitlabaction 能力大幅扩展

plugin-scaffolder-backend@1.18.0对publish:gitlabaction 进行了重要增强（dea0aafda7），新增三类属性：

• settings：透传 GitLab Project Create API 支持的通用项目设置；
• branches：创建额外分支并将其设为保护分支（protected）；
• projectVariables：设置项目级环境变量。

同时，原有属性repoVisibility与topics被标记为deprecated，其能力已由settings覆盖。此外还有两项可用性改进：当 GitLab namespace 找不到时输出有意义的错误信息（f41099bb31），以及为github:issues:label、publish:azure等 action 补充示例与测试（7dd82cc07e、733ddf7130）。

六、Catalog：OpenTelemetry 指标、处理器废弃与 stitching 铺垫

plugin-catalog-backend@1.14.0的主要变化集中在可观测性与内部架构：

• OpenTelemetry 指标插桩（78af9433c8）：为缺失的关键路径补充指标采集。仓库中的 plugins/catalog-backend/src/database/metrics.ts 展示了具体的实现模式——例如createEntitiesCountByKind同时注册 OpenTelemetry 可观测 Gauge 与旧的 Prometheus Gauge，通过单飞缓存（single-flight）与 TTL（默认 30 秒）合并并发查询，避免每次指标抓取都触发重型数据库查询；
• LocationEntityProcessor标记为废弃（7a2e2924c7）：该处理器早已不在内部使用，继续保留甚至可能有害；
• 修复 eager delete 触发的关系重拼接问题（348e8c1cdb）：被急切删除的实体未能正确触发与其有关联关系的实体重新拼接（re-stitching）；
• 延迟拼接（deferred stitching）的内部铺垫（b97e9790f0），为后续 #18062 的落地做准备。

此外，catalog-backend-module-github-org@0.1.0新增catalogModuleGithubOrgEntityProvider，支持从多个GitHub 组织摄取用户与团队（c101e683d5）；plugin-catalog-backend-module-github@0.4.4中的catalogModuleGithubOrgEntityProvider被移除，需改为从新包导入；AwsEksClusterProcessor支持 Entity 回调函数并在初始化 EKS 集群时传入 region（5abc2fd4d6）。

七、Auth 与 Kubernetes：模块化推进与新插件

7.1 认证模块

• GCP IAP：gcpIapAuthenticator.initialize()不再是async（6f142d5356，BREAKING）；
• ProxyAuthenticator.initialize()同样不再async（6f142d5356，BREAKING），与 OAuth 的等价实现保持一致；
• Microsoft provider迁移到新的独立模块包@backstage/plugin-auth-backend-module-microsoft-provider@0.1.0（2d8f7e82c1）；
• 新增 Pinniped认证模块@backstage/plugin-auth-backend-module-pinniped-provider@0.1.0（ae34255836）；
• 修复持久化 scope 在登录时无法正确恢复、以及 OAuth refresh handler 响应中 cookie 持久化 scope 缺失的问题（6c2b0793bf、8b8b1d23ae）；
• GitHub authenticator 修复了 OAuth scope 未正确持久化的问题（5d32a58b5a）；OIDC refresh 时若 token endpoint 响应缺少 scope，则回退使用请求的 scope（9ff7935152）。

7.2 Kubernetes

• 新增 Kubernetes cluster 插件（95518765ee）：管理员可以直接在 Backstage 中查看 Kubernetes 集群；
• 新增plugin-kubernetes-node@0.1.0（cbb0e3c3f4）：承载 Kubernetes 后端插件的扩展点，目前包含KubernetesObjectsProviderExtensionPoint，kubernetes-backend已改用该扩展点；
• 认证策略增强（5dac12e435）：当提供Backstage-Kubernetes-Authorization-X-X请求头时，Kubernetes API 会调用认证策略，从而支持 pinniped 或自定义策略等需要额外步骤获取 k8s token 的场景；
• KubernetesFetcher允许传入undefined的labelSelector（ae943c3bb1，BREAKING，仅影响自定义ObjectProvider实现）；
• 新增plugin-kubernetes-react、plugin-kubernetes-cluster、plugin-kubernetes-common@0.7.0，Kubernetes 插件按 ADR 11 进行重构（2d8151061c，暂无破坏性变化）。

八、其他值得关注的变化

8.1 搜索：查询长度限制可配置

plugin-search-backend@1.4.6为搜索查询设置了默认 100 字符的长度上限（16be6f9473），可通过配置文件覆盖：

search: maxTermLength: 100

8.2 后端任务指标

backend-tasks@0.5.11为后台任务新增计数与直方图指标（5db102bfdf）：

• backend_tasks.task.runs.count：任务运行总次数的 Counter；
• backend_tasks.task.runs.duration：任务运行耗时的 Histogram；

两者均带result、taskId、scope标签便于细分。同时修复了使用HumanDuration定义的任务在应用启动时被立即触发的问题（ddd76ac98d）。

8.3 配置加载器

config-loader@1.5.1新增watch选项（a4617c422a），可设为false禁用文件监听；FileConfigSource在读取到空文件时会短暂延迟后重试（773ea341d2），避免 watch 模式下文件写入未完成时读到空内容的抖动。

8.4 create-app：E2E 测试切换到 Playwright、Docker 基础镜像更新

• Cypress → Playwright（5eacd5d213）：create-app 模板的 E2E 测试改为基于 Playwright，配套新增@backstage/e2e-test-utils@0.1.0（f5b41b27a9，Initial release），用于在 monorepo 中自动发现带e2e-tests目录的包；E2E 脚本从packages/app/package.json移入根package.json的yarn test:e2e（非 CI 环境以开发模式运行）；若需要，可在项目根创建包含playwright.config.ts的.eslintignore；
• Docker 基础镜像：由node:18-bullseye-slim改为node:18-bookworm-slim（b665f2ce65、04a3f65e15），修复了 bullseye 上的镜像构建错误——需同步修改自有Dockerfile。

8.5 前端核心体验修复

• core-app-api@1.11.0的RouteResolver（及useRouteRef）对常见不安全字符进行URL 编码（c9d9bfeca2）；
• AppRouter修复了app.baseUrl含basePath时signOutTargetUrl计算错误（29e4d8b76b）；
• 整个应用包裹<Suspense>，支持在插件之外使用翻译（acca17e91a）；
• TranslationApi修复了部分情况下语言变更未通知订阅者的问题（f1b349cfba）；
• core-components：TabbedLayout点击当前激活 tab 也会触发导航（4eab5cf901），MissingAnnotationEmptyState可根据当前实体动态生成 YAML 示例（d19a827ef1）。

8.6 Jenkins 与 Home

• Jenkins 插件（前端 + 后端）新增JobRunTable组件、新路由与getBuildJobsAPI，可在 Actions 列点击图标进入 Job 运行列表页（411896faf9）；
• Jenkins 后端新增对新后端系统的支持（930ac236d8）；
• Home 插件新增 Top / Recently Visited 组件（f997f771da）。

九、升级路线建议

综合 v1.19.0 的变更，升级时建议按以下优先级处理：

1. 后端启动方式：确认已迁移至新后端系统；若仍在旧系统，可临时设置LEGACY_BACKEND_START，但应尽快迁移，因为该标志在后续版本中会被废弃并移除（见 packages/cli/CHANGELOG.md）；
2. .icon.svg文件：按上文示例迁移为.tsx+SvgIcon；
3. 实验性插件配置 API：替换__experimentalReconfigure()/__experimentalConfigure()的使用，改用国际化 API 或普通配置项；
4. 声明式前端集成（若使用 alpha API）：将at: 'id/input'改为attachTo: { id, input }，并按新createApp选项名迁移；
5. TechDocs 自定义 preparer：实现shouldCleanPreparedDirectory方法；
6. Dockerfile：将基础镜像更新为node:18-bookworm-slim。

通过本文对照仓库源码（如 packages/techdocs-cli/src/lib/mkdocsServer.ts、plugins/catalog-backend/src/database/metrics.ts），你可以进一步深入验证每个变更的实际实现，从而在升级与迁移过程中做到心中有数。

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