Backstage Docker环境下组件文档创建失败 容器返回非零退出码1

该报错本质是Backstage TechDocs调用Docker容器执行文档静态构建时进程异常退出，核心触发原因集中在配置缺失、路径错误、缓存/镜像异常、Docker权限四类问题。

• 补全mkdocs.yml必填配置
  你当前的mkdocs.yml仅配置了nav字段，缺少mkdocs强制要求的site_name参数，这是最常见的触发原因，替换为如下最小可用配置即可：

  site_name: 你的项目文档
  nav:
    - Home: index.md
  

• 核对目录结构合规性
  确认mkdocs.yml放在仓库根目录，和docs文件夹处于同一层级，index.md直接存放在docs文件夹内，不要把mkdocs.yml放到docs目录下，也不要给index.md加多余的嵌套路径。
• 清理异常缓存与旧镜像
  Windows临时目录的残留缓存、本地拉取的旧版本techdocs镜像损坏也会触发构建失败，依次执行以下操作清理：
  1. 删除临时目录下的历史构建缓存：del /f /s /q C:\Users\Admin\AppData\Local\Temp\backstage-* C:\Users\Admin\AppData\Local\Temp\techdocs-tmp-*
  2. 删除本地旧的techdocs构建镜像：docker rmi spotify/techdocs:latest，下次访问文档时Backstage会自动拉取最新版镜像，规避版本兼容问题。
• 排查Docker权限问题
  如果以上操作后仍报错，先修改Backstage配置临时切换为本地构建验证：在app-config.yaml的techdocs配置段，将builder参数从docker改为local，提前执行pip install mkdocs mkdocs-techdocs-core安装本地构建依赖后重试。如果本地构建正常，说明是Docker没有Windows C盘的访问权限，打开Docker Desktop设置-资源-文件共享，勾选C盘后保存重启Docker即可恢复Docker模式构建。

内容的提问来源于stack exchange，提问作者Veera Silamban