Backstage tech-docs配置报错Error: spawn mkdocs ENOENT如何解决
报错原因
报错信息里的spawn mkdocs ENOENT表示当前运行Backstage的系统环境找不到mkdocs可执行程序。Backstage的TechDocs模块本地构建文档时强依赖mkdocs工具链完成静态站点生成,环境缺少该依赖时就会触发该错误,和你仓库内放置的mkdocs.yml、docs目录文件、Backstage侧的组件catalog配置均无关系。
修复步骤
- 首先确认本地已安装Python 3.7及以上版本,执行
python3 --version验证版本符合要求即可。 - 执行命令安装mkdocs及TechDocs必需的核心插件:
pip3 install mkdocs mkdocs-techdocs-core
Windows系统如果默认配置了Python别名,可将pip3替换为pip执行。
- 安装完成后执行
mkdocs --version验证,命令正常返回版本号即代表安装成功。 - 如果验证命令提示找不到mkdocs,说明Python的可执行文件目录未加入系统PATH环境变量,将对应Python安装路径下的bin目录添加到PATH后重新打开终端即可。
- 重启本地运行的Backstage服务,重新访问项目文档模块即可正常完成文档构建。
内容的提问来源于stack exchange,提问作者Pablo Darde
相关产品推荐
相关产品推荐

