Backstage 实例定制化实战从插件选型到主题、Logo 与侧边栏的深度定制【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage当你的 Backstage 试点PoC经过首轮利益相关者反馈参见 docs/golden-path/adoption/004-first-stakeholder-feedback.md并且你已经清楚用户想要什么、也获得了领导层的支持之后就进入到了定制化阶段把 Backstage 打磨成真正属于自己公司的开发者门户。本文以 docs/golden-path/adoption/005-customizing-your-instance.md 为核心骨架结合仓库内主题系统源码与界面定制文档系统讲解先评估插件是复用还是自研、再低成本快速定制品牌视觉的完整路径。读完本文你将掌握插件选型的决策框架、MUI 与 Backstage UI 两套主题系统的定制方法、以及 Logo 与侧边栏的改造技巧。定制化阶段的整体原则进入定制阶段的前提是你已经通过首轮反馈确认了用户需求并且获得了继续投入的授权。此时的核心任务不再是验证价值而是把实例定制得让用户真正用起来。原文档给出了一条非常务实的原则Many organizations are tempted to spend a long time making sure the portal resembles their other offerings. This is important but shouldnt be a months long ordeal. Get it looking close enough and iterate.即做到足够接近close enough然后持续迭代。很多组织会忍不住在让门户看起来像自家其他产品上花很长时间这虽然重要但不应演变成长达数月的工程。正确做法是先把品牌视觉做到接近可用随后在后续迭代中逐步完善。这一原则同样适用于功能层面不要试图在一开始就把所有需求都实现到完美而是优先解决反馈中最痛的点。插件策略优先复用开源生态有明确缺口才自研在动手定制界面之前先回答一个战略问题你的需求能否通过现成插件满足Backstage 拥有庞大的社区插件生态官方插件目录见docs/plugins相关文档大量需求可以开箱即用式安装。原文档给出的决策建议非常明确优先从社区插件开始对于任何想解决的问题先到插件生态中寻找现成方案。安装一个社区插件远比自研一个插件成本低得多。自研的代价很高开发一个插件需要前端backstage/core-plugin-api、backstage/frontend-plugin-api、后端backstage/backend-plugin-api以及测试、发布、维护等多方面投入。在采纳故事adoption story早期很难有合理理由去承担这份成本。什么情况下值得自研当现有生态对你的公司存在**明显的缺口clear gap**时才应该自己构建否则省下维护开销。这一判断与 Backstage 的内部开源inner source理念一脉相承——正如 docs/golden-path/adoption/001-getting-started.md 所描述的成功的 Backstage 落地最终会让实例开始接收来自团队外部开发者贡献的插件。因此优先复用生态、把自研精力留给真正的缺口既符合成本逻辑也符合社区共建的长远方向。主题定制先理解两套并存的 UI 体系界面定制里工作量最大、也最容易困惑的是主题Theming。Backstage 目前同时支持两套并行 UI 体系详见 docs/conf/user-interface/index.md体系定位主题实现方式覆盖面Material UIMUILegacy原生组件体系JS 对象通过UnifiedThemeProvider注入大多数现有插件Backstage UIBUINew自研 CSS 优先体系CSS 变量与 Token快速增长聚焦新组件维护两套主题体系并非理想状态但由于 MUI 与 Backstage UI 的架构差异目前难以自动化同步主题。判断某个组件该用哪套体系去定制的方法很简单查看组件渲染出的类名如果类名以bui开头例如.bui-Button就用 Backstage UI 的 CSS 变量方式否则使用 MUI 的 JS 主题方式。因此在定制主题时你需要在两个地方维护品牌视觉一部分旧插件走 MUI 主题一部分新组件走 BUI 的 CSS 变量。下面分别展开。定制 MUILegacy主题从createUnifiedTheme开始注册自定义主题到应用MUI 主题通过backstage/theme包提供的createUnifiedTheme创建然后在packages/app/src/App.tsx中注册到createApp的themes数组import { lightTheme, darkTheme } from ./themes; // MUI themes import ./styles.css; // Backstage UI (BUI) theme const app createApp({ apis, components, themes: [ { id: light, title: Light theme, variant: light, icon: LightIcon /, Provider: ({ children }) ( UnifiedThemeProvider theme{lightTheme} children{children} / ), }, { id: dark, title: Dark theme, variant: dark, icon: DarkIcon /, Provider: ({ children }) ( UnifiedThemeProvider theme{darkTheme} children{children} / ), }, ], });themes数组中每个条目的字段含义如下名称说明id每个主题的唯一标识title显示在设置页面中供用户选择的主题名称variant取值为light或dark也称mode。应用会根据该值在body上插入data-theme-modelight或dark数据属性icon设置页面中配合标题展示的视觉元素Provider仅用于给 MUILegacy体系设置主题。BUI 基于 CSS不依赖任何全局 Provider未来 MUI 完全被 BUI 取代后该字段将不再需要注意自定义主题列表会覆盖默认主题。如果仍想保留默认主题可以直接引用backstage/theme导出的themes.light与themes.dark。务必同时提供light和dark两套模式让用户能按偏好切换。仓库中默认主题的定义见 packages/theme/src/unified/themes.tsexport const themes { light: createUnifiedTheme({ palette: palettes.light }), dark: createUnifiedTheme({ palette: palettes.dark }), };基于默认亮色主题创建新主题最常用的方式是继承内置主题再覆盖关键属性。下面的示例创建了一个基于默认亮色主题、更换字体并指定页面主题的新主题import { createBaseThemeOptions, createUnifiedTheme, palettes, } from backstage/theme; export const lightTheme createUnifiedTheme({ ...createBaseThemeOptions({ palette: palettes.light, }), fontFamily: Comic Sans MS, defaultPageTheme: home, }); export const darkTheme createUnifiedTheme({ ...createBaseThemeOptions({ palette: palettes.dark, }), fontFamily: Comic Sans MS, defaultPageTheme: home, });其中palettes.light/palettes.dark是仓库内置的完整配色方案定义于 packages/theme/src/base/palettes.ts。以palettes.light为例其结构包含background默认背景与纸张色、statusok/warning/error/running/pending/aborted 六种状态色、primary、banner通知横幅配色、navigation侧边导航的背景、指示条、文字与选中色、textContrast、link、linkHover、errorBackground等一系列 Token。createBaseThemeOptions会把这套 palette 展开为 Backstage 基础主题配置再叠加你自定义的fontFamily、defaultPageTheme等属性。覆盖品牌调色板你可以展开palettes.light后逐项覆盖形成公司品牌色import { createBaseThemeOptions, createUnifiedTheme, genPageTheme, palettes, shapes, } from backstage/theme; export const myTheme createUnifiedTheme({ ...createBaseThemeOptions({ palette: { ...palettes.light, primary: { main: #343b58 }, secondary: { main: #565a6e }, error: { main: #8c4351 }, warning: { main: #8f5e15 }, info: { main: #34548a }, success: { main: #485e30 }, background: { default: #d5d6db, paper: #d5d6db }, banner: { info: #34548a, error: #8c4351, text: #343b58, link: #565a6e, }, errorBackground: #8c4351, warningBackground: #8f5e15, infoBackground: #343b58, navigation: { background: #343b58, indicator: #8f5e15, color: #d5d6db, selectedColor: #ffffff, }, }, }), defaultPageTheme: home, fontFamily: Comic Sans MS, /* 下面的配置驱动页头Header配色 */ pageTheme: { home: genPageTheme({ colors: [#8c4351, #343b58], shape: shapes.wave }), documentation: genPageTheme({ colors: [#8c4351, #343b58], shape: shapes.wave2, }), tool: genPageTheme({ colors: [#8c4351, #343b58], shape: shapes.round }), service: genPageTheme({ colors: [#8c4351, #343b58], shape: shapes.wave, }), website: genPageTheme({ colors: [#8c4351, #343b58], shape: shapes.wave, }), library: genPageTheme({ colors: [#8c4351, #343b58], shape: shapes.wave, }), other: genPageTheme({ colors: [#8c4351, #343b58], shape: shapes.wave }), app: genPageTheme({ colors: [#8c4351, #343b58], shape: shapes.wave }), apis: genPageTheme({ colors: [#8c4351, #343b58], shape: shapes.wave }), }, });这里的pageTheme用于控制不同实体类型页面home、documentation、tool、service、website、library、other、app、apis页头的渐变配色与装饰形状shapes.wave/shapes.wave2/shapes.round。定制排版Typography在createBaseThemeOptions的typography字段中可以整体或部分覆盖排版import { createBaseThemeOptions, createUnifiedTheme, palettes, } from backstage/theme; export const myTheme createUnifiedTheme({ ...createBaseThemeOptions({ palette: palettes.light, typography: { htmlFontSize: 16, fontFamily: Arial, sans-serif, h1: { fontSize: 54, fontWeight: 700, marginBottom: 10 }, h2: { fontSize: 40, fontWeight: 700, marginBottom: 8 }, h3: { fontSize: 32, fontWeight: 700, marginBottom: 6 }, h4: { fontWeight: 700, fontSize: 28, marginBottom: 6 }, h5: { fontWeight: 700, fontSize: 24, marginBottom: 4 }, h6: { fontWeight: 700, fontSize: 20, marginBottom: 2 }, }, defaultPageTheme: home, }), });如果只想覆盖子集比如只改h1则先展开defaultTypography再覆盖import { createBaseThemeOptions, createUnifiedTheme, defaultTypography, palettes, } from backstage/theme; export const myTheme createUnifiedTheme({ ...createBaseThemeOptions({ palette: palettes.light, typography: { ...defaultTypography, htmlFontSize: 16, fontFamily: Roboto, sans-serif, h1: { fontSize: 72, fontWeight: 700, marginBottom: 10 }, }, defaultPageTheme: home, }), });引入自定义字体建议在应用src下创建assets/fonts目录存放字体文件然后通过font-face语法声明并利用MuiCssBaseline的styleOverrides注入import MyCustomFont from ../assets/fonts/My-Custom-Font.woff2; const myCustomFont { fontFamily: My-Custom-Font, fontStyle: normal, fontDisplay: swap, fontWeight: 300, src: local(My-Custom-Font), url(${MyCustomFont}) format(woff2), , }; export const myTheme createUnifiedTheme({ fontFamily: My-Custom-Font, palette: palettes.light, components: { MuiCssBaseline: { styleOverrides: { font-face: [myCustomFont], }, }, }, });如果正文与标题希望使用不同字体可以设置顶层fontFamily控制正文再在typography中为各级标题单独覆盖fontFamily。覆盖 Backstage 与 MUI 组件样式主题对象只能影响那些引用了 theme 值的 CSS 规则。例如 Backstage 组件的样式可能是这样写的const useStyles makeStylesBackstageTheme( theme ({ header: { padding: theme.spacing(3), boxShadow: 0 0 8px 3px rgba(20, 20, 20, 0.3), backgroundImage: theme.page.backgroundImage, }, }), { name: BackstageHeader }, );这里的padding来自theme.spacing、backgroundImage来自theme.page.backgroundImage改主题就能生效但boxShadow是硬编码的主题无法改变它此时必须使用组件级styleOverrides覆盖import { createBaseThemeOptions, createUnifiedTheme, palettes, } from backstage/theme; export const myTheme createUnifiedTheme({ ...createBaseThemeOptions({ palette: palettes.light, }), fontFamily: Comic Sans MS, defaultPageTheme: home, components: { BackstageHeader: { styleOverrides: { header: ({ theme }) ({ width: auto, margin: 20px, boxShadow: none, borderBottom: 4px solid ${theme.palette.primary.main}, }), }, }, }, });已知问题MUI 5 类名的v5-前缀在主应用中使用 MUI 5 组件时渲染出的 DOM 类名会带v5-前缀如v5-MuiButton-root但在代码里用buttonClasses.root获取到的是MuiButton-root两者不一致。原因是UnifiedThemeProvider配置 MUI 类名生成器的时间点偏晚应当在任何 MUI 5 组件加载之前配置。解决办法新建一个packages/app/src/MuiClassnameSetup.ts并确保它是packages/app/src/index.tsx中第一个 import// 该文件复刻 UnifiedThemeProvider 的类名生成逻辑 import { unstable_ClassNameGenerator as ClassNameGenerator } from mui/material/className; ClassNameGenerator.configure(componentName { if ((componentName ?? ).startsWith(v5-)) { return componentName; } return v5-${componentName}; });// CRITICAL: 必须是第一个 import确保静态 MUI V5 类名在任何组件加载前生成 import ./MuiClassnameSetup ...定制 Backstage UIBUI主题CSS 变量与 TokenBackstage UI 完全基于 CSS 构建默认主题已经提供全部核心 CSS 变量与组件样式。要定制品牌视觉只需新建一个 CSS 文件并在packages/app/src/App.tsx中导入其中声明的样式会覆盖默认样式文件变大后可以自行拆分、按需导入多个文件。BUI 默认在:root下使用亮色但可以通过data-theme-mode数据属性针对模式定制:root { /* 使用 :root 设置同时作用于亮/暗两套主题的样式 */ .bui-Button { background-color: #000; color: #fff; } } [data-theme-modelight] { /* 亮色主题专属样式 */ --bui-bg-app: #f8f8f8; --bui-fg-primary: #000; } [data-theme-modedark] { /* 暗色主题专属样式 */ --bui-bg-app: #333333; --bui-fg-primary: #fff; }核心 CSS 变量速查表只需调整少量变量即可快速实现品牌化全部颜色都由变量驱动可同时适配亮/暗模式Token 名称说明--bui-bg-app应用背景色全局仅使用一次--bui-bg-neutral-1叠加在--bui-bg-app之上的层级色主要用于Card、Dialog等--bui-bg-neutral-2用于抬升组件内部的内容使用频率较低--bui-bg-solid主要操作如主按钮的实心背景--bui-fg-solid实心背景之上的文字或图标颜色--bui-fg-primary主要文字或图标颜色--bui-fg-secondary次要文字或图标颜色--bui-fg-danger错误状态与破坏性操作--bui-fg-warning警告状态--bui-fg-success成功状态--bui-fg-info信息内容与中性状态--bui-border-1低对比度分隔线的细边框--bui-border-2Card、Dialog等表面周围的主边框--bui-font-regular应用主字体全部 CSS 变量分类总览基础色--bui-black、--bui-white纯黑/纯白亮暗主题下保持一致。中性背景色从--bui-bg-app到--bui-bg-neutral-4构成逐级抬升的层级体系每一级14都配套-hover、-pressed、-disabled状态变体例如--bui-bg-neutral-1-hover。实心背景色--bui-bg-solid及其-hover/-pressed/-disabled。状态背景色--bui-bg-danger、--bui-bg-warning、--bui-bg-success、--bui-bg-info。前景色--bui-fg-primary、--bui-fg-secondary、--bui-fg-disabled、--bui-fg-solid以及状态对--bui-fg-danger/--bui-fg-warning/--bui-fg-success/--bui-fg-info和背景上的--bui-fg-danger-on-bg/--bui-fg-warning-on-bg/--bui-fg-success-on-bg/--bui-fg-info-on-bg。边框色--bui-border-1、--bui-border-2以及状态边框--bui-border-danger/--bui-border-warning/--bui-border-success/--bui-border-info。特殊色--bui-ring焦点环、--bui-scrollbar、--bui-scrollbar-thumb滚动条。字体族--bui-font-regular正文无衬线字体、--bui-font-mono代码块与表格等宽字体。字重--bui-font-weight-regular、--bui-font-weight-bold。间距--bui-space是间距体系的基础单位默认0.25rem不直接被组件引用但通过它推导出全部间距值——想整体收紧或放大组件间距只需修改这一个变量。圆角--bui-radius-1默认0.125rem到--bui-radius-6默认1.25rem以及--bui-radius-full默认9999px。组件类名约定所有 BUI 组件都带有可按类名定制的 CSS 类。类名结构为组件级前缀.bui- 组件名称如.bui-Button组件属性通过data-属性表达。看到bui开头的类名就使用 CSS 变量与类选择器方式定制而不是 MUI 的 JS 主题。界面细节定制Logo 与侧边栏主题之外还有两处高频定制点Logo 与侧边栏详见 docs/conf/user-interface/logo.md 与 docs/conf/user-interface/sidebar.md。定制 Logo前端应用的src/components/Root/目录下有两个 Logo 组件LogoFull.tsx侧边栏展开时显示的大 LogoLogoIcon.tsx侧边栏收起时显示的小 Logo。替换方式有两种直接在这些组件中把返回内容换成内联 SVG或者导入 PNG 等图片格式。例如把新图片放到src/components/Root/logo/my-company-logo.png后import MyCustomLogoFull from ./logo/my-company-logo.png; const LogoFull () { return img src{MyCustomLogoFull} /; };仓库中可参考的模板实现见 packages/app-legacy/src/components/Root/LogoFull.tsx 及packages/create-app的 legacy-app 模板。为侧边栏添加子菜单侧边栏代码位于packages/app/src/components/Root/Root.tsx。通过SidebarSubmenu/SidebarSubmenuItem可以把某个导航项扩展为悬停子菜单。以把 Home 扩展为按 Catalog Kind 分类的子菜单为例import { useApp } from backstage/core-plugin-api; import { Sidebar, sidebarConfig, SidebarDivider, SidebarGroup, SidebarItem, SidebarPage, SidebarScrollWrapper, SidebarSpace, useSidebarOpenState, Link, GroupIcon, SidebarSubmenu, SidebarSubmenuItem, } from backstage/core-components;然后将SidebarItem icon{HomeIcon} tocatalog textHome /替换为SidebarItem icon{HomeIcon} tocatalog textHome SidebarSubmenu titleCatalog SidebarSubmenuItem titleDomains tocatalog?filters[kind]domain icon{useApp().getSystemIcon(kind:domain)} / SidebarSubmenuItem titleSystems tocatalog?filters[kind]system icon{useApp().getSystemIcon(kind:system)} / SidebarSubmenuItem titleComponents tocatalog?filters[kind]component icon{useApp().getSystemIcon(kind:component)} / SidebarSubmenuItem titleAPIs tocatalog?filters[kind]api icon{useApp().getSystemIcon(kind:api)} / SidebarDivider / SidebarSubmenuItem titleResources tocatalog?filters[kind]resource icon{useApp().getSystemIcon(kind:resource)} / SidebarDivider / SidebarSubmenuItem titleGroups tocatalog?filters[kind]group icon{useApp().getSystemIcon(kind:group)} / SidebarSubmenuItem titleUsers tocatalog?filters[kind]user icon{useApp().getSystemIcon(kind:user)} / /SidebarSubmenu /SidebarItem启动应用后悬停侧边栏的 Home 项即可看到按 Domain、System、Component、API、Resource、Group、User 等 Kind 分类的 Catalog 快捷子菜单。定制完成后的验证与迭代最后回到原文档的提醒定制不是一蹴而就的大工程而是做到足够接近 持续迭代的过程。落地时建议注意以下几点同时提供亮/暗两套主题让用户按偏好切换BUI 变量天然支持两种模式MUI 主题也建议同时定制light与dark。改动后验证MUI 主题改动需确认UnifiedThemeProvider正常注入、v5-前缀问题已规避BUI 样式改动可检查data-theme-mode下变量是否按预期生效。回归检查定制组件样式时先判断该组件是否引用了 theme 值如theme.spacing、theme.page.backgroundImage无法通过主题影响的硬编码样式如boxShadow要使用styleOverrides或 BUI 类选择器补充。保持迭代节奏先用品牌色、字体、Logo 这几项高频可见的元素快速接近品牌形象再在后续版本中逐步打磨细节避免陷入数月才上线的定制泥潭。至此你已经完成从了解用户需求到实例品牌化定制的闭环优先复用社区插件解决功能需求、通过 MUI 与 BUI 两套主题体系快速对齐品牌视觉、再以 Logo 和侧边栏等细节提升用户体验。接下来就可以带着这份定制成果准备进入正式发布GA阶段了。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Backstage 实例定制化实战从插件选型到主题、Logo 与侧边栏的深度定制【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage当你的 Backstage 试点PoC经过首轮利益相关者反馈参见 docs/golden-path/adoption/004-first-stakeholder-feedback.md并且你已经清楚用户想要什么、也获得了领导层的支持之后就进入到了定制化阶段把 Backstage 打磨成真正属于自己公司的开发者门户。本文以 docs/golden-path/adoption/005-customizing-your-instance.md 为核心骨架结合仓库内主题系统源码与界面定制文档系统讲解先评估插件是复用还是自研、再低成本快速定制品牌视觉的完整路径。读完本文你将掌握插件选型的决策框架、MUI 与 Backstage UI 两套主题系统的定制方法、以及 Logo 与侧边栏的改造技巧。定制化阶段的整体原则进入定制阶段的前提是你已经通过首轮反馈确认了用户需求并且获得了继续投入的授权。此时的核心任务不再是验证价值而是把实例定制得让用户真正用起来。原文档给出了一条非常务实的原则Many organizations are tempted to spend a long time making sure the portal resembles their other offerings. This is important but shouldnt be a months long ordeal. Get it looking close enough and iterate.即做到足够接近close enough然后持续迭代。很多组织会忍不住在让门户看起来像自家其他产品上花很长时间这虽然重要但不应演变成长达数月的工程。正确做法是先把品牌视觉做到接近可用随后在后续迭代中逐步完善。这一原则同样适用于功能层面不要试图在一开始就把所有需求都实现到完美而是优先解决反馈中最痛的点。插件策略优先复用开源生态有明确缺口才自研在动手定制界面之前先回答一个战略问题你的需求能否通过现成插件满足Backstage 拥有庞大的社区插件生态官方插件目录见docs/plugins相关文档大量需求可以开箱即用式安装。原文档给出的决策建议非常明确优先从社区插件开始对于任何想解决的问题先到插件生态中寻找现成方案。安装一个社区插件远比自研一个插件成本低得多。自研的代价很高开发一个插件需要前端backstage/core-plugin-api、backstage/frontend-plugin-api、后端backstage/backend-plugin-api以及测试、发布、维护等多方面投入。在采纳故事adoption story早期很难有合理理由去承担这份成本。什么情况下值得自研当现有生态对你的公司存在**明显的缺口clear gap**时才应该自己构建否则省下维护开销。这一判断与 Backstage 的内部开源inner source理念一脉相承——正如 docs/golden-path/adoption/001-getting-started.md 所描述的成功的 Backstage 落地最终会让实例开始接收来自团队外部开发者贡献的插件。因此优先复用生态、把自研精力留给真正的缺口既符合成本逻辑也符合社区共建的长远方向。主题定制先理解两套并存的 UI 体系界面定制里工作量最大、也最容易困惑的是主题Theming。Backstage 目前同时支持两套并行 UI 体系详见 docs/conf/user-interface/index.md体系定位主题实现方式覆盖面Material UIMUILegacy原生组件体系JS 对象通过UnifiedThemeProvider注入大多数现有插件Backstage UIBUINew自研 CSS 优先体系CSS 变量与 Token快速增长聚焦新组件维护两套主题体系并非理想状态但由于 MUI 与 Backstage UI 的架构差异目前难以自动化同步主题。判断某个组件该用哪套体系去定制的方法很简单查看组件渲染出的类名如果类名以bui开头例如.bui-Button就用 Backstage UI 的 CSS 变量方式否则使用 MUI 的 JS 主题方式。因此在定制主题时你需要在两个地方维护品牌视觉一部分旧插件走 MUI 主题一部分新组件走 BUI 的 CSS 变量。下面分别展开。定制 MUILegacy主题从createUnifiedTheme开始注册自定义主题到应用MUI 主题通过backstage/theme包提供的createUnifiedTheme创建然后在packages/app/src/App.tsx中注册到createApp的themes数组import { lightTheme, darkTheme } from ./themes; // MUI themes import ./styles.css; // Backstage UI (BUI) theme const app createApp({ apis, components, themes: [ { id: light, title: Light theme, variant: light, icon: LightIcon /, Provider: ({ children }) ( UnifiedThemeProvider theme{lightTheme} children{children} / ), }, { id: dark, title: Dark theme, variant: dark, icon: DarkIcon /, Provider: ({ children }) ( UnifiedThemeProvider theme{darkTheme} children{children} / ), }, ], });themes数组中每个条目的字段含义如下名称说明id每个主题的唯一标识title显示在设置页面中供用户选择的主题名称variant取值为light或dark也称mode。应用会根据该值在body上插入data-theme-modelight或dark数据属性icon设置页面中配合标题展示的视觉元素Provider仅用于给 MUILegacy体系设置主题。BUI 基于 CSS不依赖任何全局 Provider未来 MUI 完全被 BUI 取代后该字段将不再需要注意自定义主题列表会覆盖默认主题。如果仍想保留默认主题可以直接引用backstage/theme导出的themes.light与themes.dark。务必同时提供light和dark两套模式让用户能按偏好切换。仓库中默认主题的定义见 packages/theme/src/unified/themes.tsexport const themes { light: createUnifiedTheme({ palette: palettes.light }), dark: createUnifiedTheme({ palette: palettes.dark }), };基于默认亮色主题创建新主题最常用的方式是继承内置主题再覆盖关键属性。下面的示例创建了一个基于默认亮色主题、更换字体并指定页面主题的新主题import { createBaseThemeOptions, createUnifiedTheme, palettes, } from backstage/theme; export const lightTheme createUnifiedTheme({ ...createBaseThemeOptions({ palette: palettes.light, }), fontFamily: Comic Sans MS, defaultPageTheme: home, }); export const darkTheme createUnifiedTheme({ ...createBaseThemeOptions({ palette: palettes.dark, }), fontFamily: Comic Sans MS, defaultPageTheme: home, });其中palettes.light/palettes.dark是仓库内置的完整配色方案定义于 packages/theme/src/base/palettes.ts。以palettes.light为例其结构包含background默认背景与纸张色、statusok/warning/error/running/pending/aborted 六种状态色、primary、banner通知横幅配色、navigation侧边导航的背景、指示条、文字与选中色、textContrast、link、linkHover、errorBackground等一系列 Token。createBaseThemeOptions会把这套 palette 展开为 Backstage 基础主题配置再叠加你自定义的fontFamily、defaultPageTheme等属性。覆盖品牌调色板你可以展开palettes.light后逐项覆盖形成公司品牌色import { createBaseThemeOptions, createUnifiedTheme, genPageTheme, palettes, shapes, } from backstage/theme; export const myTheme createUnifiedTheme({ ...createBaseThemeOptions({ palette: { ...palettes.light, primary: { main: #343b58 }, secondary: { main: #565a6e }, error: { main: #8c4351 }, warning: { main: #8f5e15 }, info: { main: #34548a }, success: { main: #485e30 }, background: { default: #d5d6db, paper: #d5d6db }, banner: { info: #34548a, error: #8c4351, text: #343b58, link: #565a6e, }, errorBackground: #8c4351, warningBackground: #8f5e15, infoBackground: #343b58, navigation: { background: #343b58, indicator: #8f5e15, color: #d5d6db, selectedColor: #ffffff, }, }, }), defaultPageTheme: home, fontFamily: Comic Sans MS, /* 下面的配置驱动页头Header配色 */ pageTheme: { home: genPageTheme({ colors: [#8c4351, #343b58], shape: shapes.wave }), documentation: genPageTheme({ colors: [#8c4351, #343b58], shape: shapes.wave2, }), tool: genPageTheme({ colors: [#8c4351, #343b58], shape: shapes.round }), service: genPageTheme({ colors: [#8c4351, #343b58], shape: shapes.wave, }), website: genPageTheme({ colors: [#8c4351, #343b58], shape: shapes.wave, }), library: genPageTheme({ colors: [#8c4351, #343b58], shape: shapes.wave, }), other: genPageTheme({ colors: [#8c4351, #343b58], shape: shapes.wave }), app: genPageTheme({ colors: [#8c4351, #343b58], shape: shapes.wave }), apis: genPageTheme({ colors: [#8c4351, #343b58], shape: shapes.wave }), }, });这里的pageTheme用于控制不同实体类型页面home、documentation、tool、service、website、library、other、app、apis页头的渐变配色与装饰形状shapes.wave/shapes.wave2/shapes.round。定制排版Typography在createBaseThemeOptions的typography字段中可以整体或部分覆盖排版import { createBaseThemeOptions, createUnifiedTheme, palettes, } from backstage/theme; export const myTheme createUnifiedTheme({ ...createBaseThemeOptions({ palette: palettes.light, typography: { htmlFontSize: 16, fontFamily: Arial, sans-serif, h1: { fontSize: 54, fontWeight: 700, marginBottom: 10 }, h2: { fontSize: 40, fontWeight: 700, marginBottom: 8 }, h3: { fontSize: 32, fontWeight: 700, marginBottom: 6 }, h4: { fontWeight: 700, fontSize: 28, marginBottom: 6 }, h5: { fontWeight: 700, fontSize: 24, marginBottom: 4 }, h6: { fontWeight: 700, fontSize: 20, marginBottom: 2 }, }, defaultPageTheme: home, }), });如果只想覆盖子集比如只改h1则先展开defaultTypography再覆盖import { createBaseThemeOptions, createUnifiedTheme, defaultTypography, palettes, } from backstage/theme; export const myTheme createUnifiedTheme({ ...createBaseThemeOptions({ palette: palettes.light, typography: { ...defaultTypography, htmlFontSize: 16, fontFamily: Roboto, sans-serif, h1: { fontSize: 72, fontWeight: 700, marginBottom: 10 }, }, defaultPageTheme: home, }), });引入自定义字体建议在应用src下创建assets/fonts目录存放字体文件然后通过font-face语法声明并利用MuiCssBaseline的styleOverrides注入import MyCustomFont from ../assets/fonts/My-Custom-Font.woff2; const myCustomFont { fontFamily: My-Custom-Font, fontStyle: normal, fontDisplay: swap, fontWeight: 300, src: local(My-Custom-Font), url(${MyCustomFont}) format(woff2), , }; export const myTheme createUnifiedTheme({ fontFamily: My-Custom-Font, palette: palettes.light, components: { MuiCssBaseline: { styleOverrides: { font-face: [myCustomFont], }, }, }, });如果正文与标题希望使用不同字体可以设置顶层fontFamily控制正文再在typography中为各级标题单独覆盖fontFamily。覆盖 Backstage 与 MUI 组件样式主题对象只能影响那些引用了 theme 值的 CSS 规则。例如 Backstage 组件的样式可能是这样写的const useStyles makeStylesBackstageTheme( theme ({ header: { padding: theme.spacing(3), boxShadow: 0 0 8px 3px rgba(20, 20, 20, 0.3), backgroundImage: theme.page.backgroundImage, }, }), { name: BackstageHeader }, );这里的padding来自theme.spacing、backgroundImage来自theme.page.backgroundImage改主题就能生效但boxShadow是硬编码的主题无法改变它此时必须使用组件级styleOverrides覆盖import { createBaseThemeOptions, createUnifiedTheme, palettes, } from backstage/theme; export const myTheme createUnifiedTheme({ ...createBaseThemeOptions({ palette: palettes.light, }), fontFamily: Comic Sans MS, defaultPageTheme: home, components: { BackstageHeader: { styleOverrides: { header: ({ theme }) ({ width: auto, margin: 20px, boxShadow: none, borderBottom: 4px solid ${theme.palette.primary.main}, }), }, }, }, });已知问题MUI 5 类名的v5-前缀在主应用中使用 MUI 5 组件时渲染出的 DOM 类名会带v5-前缀如v5-MuiButton-root但在代码里用buttonClasses.root获取到的是MuiButton-root两者不一致。原因是UnifiedThemeProvider配置 MUI 类名生成器的时间点偏晚应当在任何 MUI 5 组件加载之前配置。解决办法新建一个packages/app/src/MuiClassnameSetup.ts并确保它是packages/app/src/index.tsx中第一个 import// 该文件复刻 UnifiedThemeProvider 的类名生成逻辑 import { unstable_ClassNameGenerator as ClassNameGenerator } from mui/material/className; ClassNameGenerator.configure(componentName { if ((componentName ?? ).startsWith(v5-)) { return componentName; } return v5-${componentName}; });// CRITICAL: 必须是第一个 import确保静态 MUI V5 类名在任何组件加载前生成 import ./MuiClassnameSetup ...定制 Backstage UIBUI主题CSS 变量与 TokenBackstage UI 完全基于 CSS 构建默认主题已经提供全部核心 CSS 变量与组件样式。要定制品牌视觉只需新建一个 CSS 文件并在packages/app/src/App.tsx中导入其中声明的样式会覆盖默认样式文件变大后可以自行拆分、按需导入多个文件。BUI 默认在:root下使用亮色但可以通过data-theme-mode数据属性针对模式定制:root { /* 使用 :root 设置同时作用于亮/暗两套主题的样式 */ .bui-Button { background-color: #000; color: #fff; } } [data-theme-modelight] { /* 亮色主题专属样式 */ --bui-bg-app: #f8f8f8; --bui-fg-primary: #000; } [data-theme-modedark] { /* 暗色主题专属样式 */ --bui-bg-app: #333333; --bui-fg-primary: #fff; }核心 CSS 变量速查表只需调整少量变量即可快速实现品牌化全部颜色都由变量驱动可同时适配亮/暗模式Token 名称说明--bui-bg-app应用背景色全局仅使用一次--bui-bg-neutral-1叠加在--bui-bg-app之上的层级色主要用于Card、Dialog等--bui-bg-neutral-2用于抬升组件内部的内容使用频率较低--bui-bg-solid主要操作如主按钮的实心背景--bui-fg-solid实心背景之上的文字或图标颜色--bui-fg-primary主要文字或图标颜色--bui-fg-secondary次要文字或图标颜色--bui-fg-danger错误状态与破坏性操作--bui-fg-warning警告状态--bui-fg-success成功状态--bui-fg-info信息内容与中性状态--bui-border-1低对比度分隔线的细边框--bui-border-2Card、Dialog等表面周围的主边框--bui-font-regular应用主字体全部 CSS 变量分类总览基础色--bui-black、--bui-white纯黑/纯白亮暗主题下保持一致。中性背景色从--bui-bg-app到--bui-bg-neutral-4构成逐级抬升的层级体系每一级14都配套-hover、-pressed、-disabled状态变体例如--bui-bg-neutral-1-hover。实心背景色--bui-bg-solid及其-hover/-pressed/-disabled。状态背景色--bui-bg-danger、--bui-bg-warning、--bui-bg-success、--bui-bg-info。前景色--bui-fg-primary、--bui-fg-secondary、--bui-fg-disabled、--bui-fg-solid以及状态对--bui-fg-danger/--bui-fg-warning/--bui-fg-success/--bui-fg-info和背景上的--bui-fg-danger-on-bg/--bui-fg-warning-on-bg/--bui-fg-success-on-bg/--bui-fg-info-on-bg。边框色--bui-border-1、--bui-border-2以及状态边框--bui-border-danger/--bui-border-warning/--bui-border-success/--bui-border-info。特殊色--bui-ring焦点环、--bui-scrollbar、--bui-scrollbar-thumb滚动条。字体族--bui-font-regular正文无衬线字体、--bui-font-mono代码块与表格等宽字体。字重--bui-font-weight-regular、--bui-font-weight-bold。间距--bui-space是间距体系的基础单位默认0.25rem不直接被组件引用但通过它推导出全部间距值——想整体收紧或放大组件间距只需修改这一个变量。圆角--bui-radius-1默认0.125rem到--bui-radius-6默认1.25rem以及--bui-radius-full默认9999px。组件类名约定所有 BUI 组件都带有可按类名定制的 CSS 类。类名结构为组件级前缀.bui- 组件名称如.bui-Button组件属性通过data-属性表达。看到bui开头的类名就使用 CSS 变量与类选择器方式定制而不是 MUI 的 JS 主题。界面细节定制Logo 与侧边栏主题之外还有两处高频定制点Logo 与侧边栏详见 docs/conf/user-interface/logo.md 与 docs/conf/user-interface/sidebar.md。定制 Logo前端应用的src/components/Root/目录下有两个 Logo 组件LogoFull.tsx侧边栏展开时显示的大 LogoLogoIcon.tsx侧边栏收起时显示的小 Logo。替换方式有两种直接在这些组件中把返回内容换成内联 SVG或者导入 PNG 等图片格式。例如把新图片放到src/components/Root/logo/my-company-logo.png后import MyCustomLogoFull from ./logo/my-company-logo.png; const LogoFull () { return img src{MyCustomLogoFull} /; };仓库中可参考的模板实现见 packages/app-legacy/src/components/Root/LogoFull.tsx 及packages/create-app的 legacy-app 模板。为侧边栏添加子菜单侧边栏代码位于packages/app/src/components/Root/Root.tsx。通过SidebarSubmenu/SidebarSubmenuItem可以把某个导航项扩展为悬停子菜单。以把 Home 扩展为按 Catalog Kind 分类的子菜单为例import { useApp } from backstage/core-plugin-api; import { Sidebar, sidebarConfig, SidebarDivider, SidebarGroup, SidebarItem, SidebarPage, SidebarScrollWrapper, SidebarSpace, useSidebarOpenState, Link, GroupIcon, SidebarSubmenu, SidebarSubmenuItem, } from backstage/core-components;然后将SidebarItem icon{HomeIcon} tocatalog textHome /替换为SidebarItem icon{HomeIcon} tocatalog textHome SidebarSubmenu titleCatalog SidebarSubmenuItem titleDomains tocatalog?filters[kind]domain icon{useApp().getSystemIcon(kind:domain)} / SidebarSubmenuItem titleSystems tocatalog?filters[kind]system icon{useApp().getSystemIcon(kind:system)} / SidebarSubmenuItem titleComponents tocatalog?filters[kind]component icon{useApp().getSystemIcon(kind:component)} / SidebarSubmenuItem titleAPIs tocatalog?filters[kind]api icon{useApp().getSystemIcon(kind:api)} / SidebarDivider / SidebarSubmenuItem titleResources tocatalog?filters[kind]resource icon{useApp().getSystemIcon(kind:resource)} / SidebarDivider / SidebarSubmenuItem titleGroups tocatalog?filters[kind]group icon{useApp().getSystemIcon(kind:group)} / SidebarSubmenuItem titleUsers tocatalog?filters[kind]user icon{useApp().getSystemIcon(kind:user)} / /SidebarSubmenu /SidebarItem启动应用后悬停侧边栏的 Home 项即可看到按 Domain、System、Component、API、Resource、Group、User 等 Kind 分类的 Catalog 快捷子菜单。定制完成后的验证与迭代最后回到原文档的提醒定制不是一蹴而就的大工程而是做到足够接近 持续迭代的过程。落地时建议注意以下几点同时提供亮/暗两套主题让用户按偏好切换BUI 变量天然支持两种模式MUI 主题也建议同时定制light与dark。改动后验证MUI 主题改动需确认UnifiedThemeProvider正常注入、v5-前缀问题已规避BUI 样式改动可检查data-theme-mode下变量是否按预期生效。回归检查定制组件样式时先判断该组件是否引用了 theme 值如theme.spacing、theme.page.backgroundImage无法通过主题影响的硬编码样式如boxShadow要使用styleOverrides或 BUI 类选择器补充。保持迭代节奏先用品牌色、字体、Logo 这几项高频可见的元素快速接近品牌形象再在后续版本中逐步打磨细节避免陷入数月才上线的定制泥潭。至此你已经完成从了解用户需求到实例品牌化定制的闭环优先复用社区插件解决功能需求、通过 MUI 与 BUI 两套主题体系快速对齐品牌视觉、再以 Logo 和侧边栏等细节提升用户体验。接下来就可以带着这份定制成果准备进入正式发布GA阶段了。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
