Backstage TechDocs中Kroki生成的图片加载失败如何解决？

问题根源 #

生成的HTML中Kroki图片使用了绝对根路径（/images/kroki_generated/...），但Backstage的文档页面位于/docs/default/component/...路径下，浏览器请求根路径图片时，会被Backstage的前端路由拦截，返回应用首页而非存储的SVG文件。

解决方案 #

1. 配置MkDocs生成相对路径链接 #

修改mkdocs.yaml，添加基础路径配置，强制生成相对路径的图片链接：

site_url: .
use_directory_urls: false
plugins:
  - techdocs-core
  - kroki:
      DownloadImages: true
      FencePrefix: ''
      HttpMethod: POST
      ServerURL: http://localhost:8000

site_url: .会让MkDocs以当前文档目录为基准生成相对路径，避免使用根路径；use_directory_urls: false确保页面URL不会自动省略index.html，保证相对路径解析正确。

2. 直接指定Kroki插件的图片路径 #

若上述配置不生效，可在Kroki插件配置中明确指定相对路径：

plugins:
  - techdocs-core
  - kroki:
      DownloadImages: true
      FencePrefix: ''
      HttpMethod: POST
      ServerURL: http://localhost:8000
      ImageDir: './images/kroki_generated'
      ImageUrlPath: './images/kroki_generated'

此配置会强制Kroki生成./images/kroki_generated/xxx.svg格式的相对路径链接，浏览器会从当前文档所在路径下请求图片。

3. 确认CI/CD发布的文件结构 #

确保techdocs-cli publish命令将本地生成的完整站点目录（包括images/kroki_generated）同步到Azure存储，且存储中的文件结构与本地完全一致：

• 本地生成结构：site/docs/default/component/<组件名称>/<文档>/index.html旁需包含images/kroki_generated/目录
• Azure存储中对应路径需保持相同层级，确保相对路径请求能定位到图片文件

4. 检查Backstage的TechDocs存储配置 #

在app-config.yaml中确认TechDocs的发布配置正确指向Azure存储，保证Backstage能正确访问存储中的静态资源：

techdocs:
  builder: 'external'
  publisher:
    type: 'azureBlobStorage'
    azureBlobStorage:
      containerName: '<你的存储容器名>'
      accountName: '<你的存储账户名>'
      accountKey: '<你的存储密钥>'
      endpoint: '<存储终结点URL>'

验证步骤 #

1. 重新执行techdocs-cli generate，检查生成的HTML中图片链接是否为相对路径格式
2. 直接访问Azure存储中的SVG文件URL，确认文件可正常打开
3. 访问Backstage内的文档页面，检查图片是否加载成功

内容的提问来源于stack exchange，提问作者Mike Schenk