企业官网建设流程全解析

Backstage v1.39.0-next.2 版本解析：Gerrit 编辑入口、catalog-import 国际化与翻译 API 的 JSX 插值能力

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

本篇技术指南围绕 Backstage 官方发布文档 v1.39.0-next.2 changelog 展开，系统梳理该预发布版本中约 60 个包的变化，重点剖析三个具有实战价值的主题：@backstage/integration为 Gerrit 3.9+ 新增的 Edit URL 能力及其开关配置、@backstage/plugin-catalog-import的国际化（i18n）支持及随之而来的破坏性变更、以及贯穿core-plugin-api/core-app-api/test-utils的翻译 API JSX 元素插值增强。读完本文，你将掌握这些变更的配置方法、迁移要点与底层实现原理。

版本概览：一个聚焦"翻译体系"与"代码托管集成"的预发布版本

v1.39.0-next.2是 Backstage 面向 v1.39.0 正式版的第二个预发布（next）版本。与所有next版本一样，它面向早期验证者，包含完整的变更记录但可能仍处于迭代之中。本次版本中大多数包仅有依赖更新（Patch Changes），真正的功能亮点集中在以下几处：

• Minor（新增功能）：@backstage/integration@1.17.0-next.2新增 Gerrit 3.9+ Edit URL 功能（提交f134cea）；@backstage/plugin-catalog-import@0.13.0-next.2的generateStepper签名变更（提交e2fd549，Breaking）。
• Patch（修复与增强）：翻译 API 支持 JSX 元素插值（提交73f6cc3、b573341）、catalog-import插件新增 i18n 支持（提交66a1140）、GithubUrlReader改用options中的 token 拉取仓库详情（提交0e7a640）、AWS STS region 回退逻辑修复（提交db4630e）等。

各包版本号、变更类别与依赖关系的完整清单，可直接查阅 v1.39.0-next.2-changelog.md 原文。

重点一：Gerrit 3.9+ Edit URL 功能

本次版本最值得关注的功能性新增，来自@backstage/integration@1.17.0-next.2的 Minor Changes：

f134cea: Implement Edit URL feature for Gerrit 3.9+. It's possible to disable the edit url by adding thedisableEditUrl: trueconfig in the Gerrit integration.

功能背景与 URL 形态

Gerrit 3.9 之后，服务端提供了基于 Web 的文件编辑入口，Backstage 借此为 Gerrit 集成实现了resolveEditUrl。从实现看，该 URL 由 buildGerritEditUrl 生成，其结构为：

{baseUrl}/admin/repos/edit/repo/{project}/branch/refs/heads/{branch}/file/{filePath}

例如在 GerritIntegration.test.ts 中验证的用例，输入的 Gitiles 浏览地址：

https://gerrit-review.example.com/gitiles/backstage/backstage/+/refs/heads/master/catalog-info.yaml

会被解析并转换为编辑入口：

https://gerrit-review.example.com/admin/repos/edit/repo/backstage/backstage/branch/refs/heads/master/file/catalog-info.yaml

实现路径为：resolveEditUrl先用parseGitilesUrlRef从 Gitiles URL 中解析出project、ref、path三个要素，再调用buildGerritEditUrl拼装出编辑页面地址。整个转换逻辑集中在 GerritIntegration.resolveEditUrl。

通过disableEditUrl开关控制行为

对于 Gerrit 版本低于 3.9、或出于安全与体验考量不希望暴露编辑入口的实例，可以在 Gerrit 集成配置中关闭该功能。配置项disableEditUrl是可选布尔值，由 readGerritIntegrationConfig 通过config.getOptionalBoolean('disableEditUrl')读取，类型定义与注释位于 config.ts 的 GerritIntegrationConfig。

启用开关后，resolveEditUrl会直接原样返回输入 URL，不做任何转换：

resolveEditUrl(url: string): string { if (this.config.disableEditUrl) { return url; } // ... 解析并构建编辑 URL }

对应的行为在 GerritIntegration.test.ts 中有完整覆盖：当disableEditUrl: true时，输入 URL 被原样返回；当disableEditUrl: false时，则返回转换后的编辑 URL。配置解析侧的校验与默认值（undefined）行为则由 config.test.ts 验证。

配置示例

在app-config.yaml（或独立的后端配置）的integrations.gerrit节点下，完整的 Gerrit 集成配置形如：

integrations: gerrit: - host: gerrit-review.example.com baseUrl: https://gerrit-review.example.com gitilesBaseUrl: https://gerrit-review.example.com/gitiles # 针对 Gerrit < 3.9 或不需要编辑入口的实例，关闭 Edit URL 功能 disableEditUrl: true

注意：host与gitilesBaseUrl为必填项，baseUrl缺省时会自动回退为https://{host}（见 config.ts 的默认值逻辑）。该配置的完整字段（baseUrl、cloneUrl、username、password、commitSigningKey等）与校验规则均定义在同文件中。

重点二：catalog-import 插件的 i18n 支持与 Breaking 变更

@backstage/plugin-catalog-import@0.13.0-next.2同时包含一个 Minor（破坏性）变更与一个 Patch（新增能力）：

• e2fd549（BREAKING）：generateStepper与defaultGenerateStepper现在要求必须传入 translation 参数，以支持翻译。
• 66a1140：为catalog-import插件整体添加 i18n 支持。

破坏性变更的签名变化

此前，自定义导入流程的开发者若通过ImportStepperProps.generateStepper注入自定义 stepper 生成函数，签名只接收flow与defaults两个参数。升级后，该函数必须接收第三个参数——翻译函数t：

generateStepper?: ( flow: ImportFlows, defaults: StepperProvider, t: TranslationFunction<typeof catalogImportTranslationRef.T>, ) => StepperProvider;

这一新签名定义在 ImportStepper.tsx 的 ImportStepperProps，默认实现 defaultGenerateStepper 已同步升级。在 ImportStepper 组件内部，翻译函数来自useTranslationRef(catalogImportTranslationRef)，并通过useMemo传入generateStepper(state.activeFlow, defaultStepper, t)。

翻译引用catalogImportTranslationRef定义于插件的 translation 模块，并在 alpha.tsx 中对外导出。

迁移指南：自定义 stepper 如何适配

如果你在应用中覆盖了generateStepper，升级到0.13.0-next.2后需要：

1. 将第三个参数t加入函数签名；
2. 将原先硬编码的界面文案（如importStepper.singleLocation.title）替换为t('...')调用；
3. 使用默认实现中相同的翻译 key 结构。例如 defaults.tsx 中single-location流程的prepare步骤标签即通过t('importStepper.singleLocation.title')与t('importStepper.singleLocation.description')渲染。

如果你未覆盖generateStepper（使用默认行为），则无需改动，破坏性变更不影响默认路径。

重点三：翻译 API 支持 JSX 元素插值

本版本围绕国际化另一条主线是翻译插值能力的增强，涉及三个包，均由提交73f6cc3（及b573341）引入：

• @backstage/core-plugin-api@1.10.7-next.0：TranslationApi现在支持将 JSX 元素直接作为插值值传给翻译函数。若提供的任一插值值是 JSX 元素，翻译函数将返回 JSX 元素而非字符串。
• @backstage/core-app-api@1.16.2-next.0：I18nextTranslationApi同步支持 JSX 元素的插值。
• @backstage/test-utils@1.7.8-next.1：MockTranslationApi增加对 JSX 元素插值的支持，便于在测试环境中验证此类翻译。

这一能力让"翻译字符串中嵌入可点击链接、强调文本等富内容"成为可能。例如模板中包含<Link>或<strong>占位符时，应用侧可以这样调用：

const { t } = useTranslationRef(myTranslationRef); // 插值值为 JSX 元素时，返回 JSX 而非字符串 const message = t('welcome.text', { user: <strong>{userName}</strong>, docsLink: <Link to="/docs">documentation</Link>, });

MockTranslationApi的同步升级意味着基于@backstage/test-utils的组件测试可以直接覆盖该行为，无需额外 mock。

其他值得关注的 Patch 变更

除上述三大主题外，本版本还包含若干值得注意的修复与增强：

升级建议与验证方式

1. 关注 Breaking 变更：若你的应用覆盖了generateStepper，升级@backstage/plugin-catalog-import前务必按上文迁移指南调整签名；其余包均为兼容性变更。
2. 验证 Gerrit 编辑入口：升级@backstage/integration后，可在本地起一个 Gerrit 3.9+ 实例，通过catalog-import或 url reader 流程触发resolveEditUrl，并结合disableEditUrl: true/false两种配置分别验证（仓库测试 GerritIntegration.test.ts 给出了两种模式的期望输出，可直接作为断言基准）。
3. 翻译 API 回归：若插件代码依赖TranslationApi的字符串返回值，确认插值参数中不混入 JSX 元素；测试环境建议同步升级@backstage/test-utils，以利用MockTranslationApi的 JSX 插值支持。

当前仓库中，完整的包级变更清单可分别查阅各包 CHANGELOG，例如 packages/integration/CHANGELOG.md 与 plugins/catalog-import/CHANGELOG.md，它们与 v1.39.0-next.2-changelog.md 相互印证，可作为升级与代码评审的对照依据。

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