Backstage构建Docker镜像提示backstage-cli未找到错误排查

问题现象 #

基于Backstage官方源码构建Docker镜像，Dockerfile参照官方多阶段构建规范编写，构建执行到yarn build步骤时抛出错误，核心报错信息如下：

#19 [build 10/10] RUN yarn build
#19 sha256:230493e99704b51c04c3dfbb54c48c05c41decce3b8cac9992d7ce37b5211ea8
#19 1.208 yarn run v1.22.1
#19 1.257 $ backstage-cli repo build --all
#19 1.272 /bin/sh: 1: backstage-cli: not found
#19 1.287 error Command failed with exit code 127.
#19 1.287 info Visit yarn official documentation for details about this command.
#19 ERROR: executor failed running [/bin/sh -c yarn build]: exit code: 127

根因说明 #

报错退出码127代表shell找不到指定的执行命令，该问题均由build阶段依赖缺失或配置顺序错误导致，对应遗漏的操作/配置如下：

• build阶段执行yarn install时错误添加了--production参数。backstage-cli属于@backstage/cli包提供的命令，该包被归类在devDependencies开发依赖中，生产模式安装会自动跳过所有开发依赖，导致命令不存在
• Dockerfile执行顺序错误：未先完成依赖安装就复制源码执行build，或复制文件时遗漏了根目录package.json、yarn.lock配置文件，导致依赖安装不完整
• 多阶段构建过程中build层的node_modules目录被误删、或被.dockerignore规则排除，执行build命令时无法读取本地安装的依赖包
• 工作目录配置错误，执行yarn build时不在项目根目录，无法读取当前目录下node_modules/.bin中的软链命令

修复方案 #

调整build阶段的Dockerfile逻辑，按以下顺序编写构建步骤：

1. 声明build阶段基础镜像后，先配置工作目录，例如WORKDIR /app
2. 优先复制项目根目录的依赖配置文件：

   COPY package.json yarn.lock .yarnrc tsconfig.json ./
   COPY packages/*/package.json ./packages/
   

3. 执行依赖安装，禁止添加--production参数：

   RUN yarn install --frozen-lockfile
   

4. 复制全量项目源码到工作目录
5. 再执行build命令：

   RUN yarn build
   

额外检查项：

• 确认.dockerignore规则没有排除build阶段需要的node_modules目录、各package下的配置文件
• 确认根目录package.json的devDependencies中存在@backstage/cli依赖，且版本与当前Backstage版本匹配
• 不要通过全局安装@backstage/cli的方式绕过该问题，全局安装的CLI版本与项目版本不匹配会引发更多构建异常

内容的提问来源于stack exchange，提问作者Ena Jain