GitHub Workflow部署项目至IONOS时报build目录不存在错误

问题背景 #

需要通过GitHub Workflow将托管在GitHub上的项目部署到IONOS平台，使用的deploy-now.yaml配置文件内容如下：

name: Deploy Now

on:
  - push
  - workflow_dispatch

jobs:
  deploy-now:
    runs-on: ubuntu-latest
    steps:
      - name: Fetch project data
        uses: ionos-deploy-now/retrieve-project-info-action@v1
        id: project
        with:
          api-key: ${{ secrets.IONOS_API_KEY }}
          project: ${{ secrets.IONOS_PROJECT_ID }}
          service-host: api-eu.ionos.space
      - name: checkout
        if: ${{ steps.project.outputs.deployment-enabled == 'true' }}
        uses: actions/checkout@v2
        with:
          submodules: 'recursive'
      - name: Setup Node.js 14.x
        if: ${{ steps.project.outputs.deployment-enabled == 'true' }}
        uses: actions/setup-node@v1
        with:
          node-version: 14.x
      - name: Prepare project environment
        if: ${{ steps.project.outputs.deployment-enabled == 'true' }}
        run: |
          npm install --global yarn
          yarn install --frozen-lockfile
      - name: Build project
        if: ${{ steps.project.outputs.deployment-enabled == 'true' }}
        run: yarn build
        env:
          mint.hopegalaxy: ${{ steps.project.outputs.site-url }}
          app: true
      - name: Deploy build
        if: ${{ steps.project.outputs.deployment-enabled == 'true' }}
        uses: ionos-deploy-now/deploy-to-ionos-action@v1
        with:
          api-key: ${{ secrets.IONOS_API_KEY }}
          bootstrap-deploy: ${{ steps.project.outputs.bootstrap-deploy }}
          branch-id: ${{ steps.project.outputs.branch-id }}
          dist-folder: build
          project: ${{ secrets.IONOS_PROJECT_ID }}
          remote-host: ${{ steps.project.outputs.remote-host }}
          service-host: api-eu.ionos.space
          storage-quota: ${{ steps.project.outputs.storage-quota }}

推送代码触发工作流后报错：Publish directory 'build' does not exist in project，日志显示构建步骤已成功执行，无法定位问题原因。
工作流运行截图：

排查方向与解决方案 #

• 核对构建产物实际输出目录
  当前部署步骤指定的发布目录为build，但不同前端框架、不同构建配置的默认输出目录存在差异：Vite、Vue CLI默认输出dist目录，旧版Create React App默认输出build目录，自定义构建配置后输出路径也可能变更。先在本地项目根目录执行yarn build，确认执行完成后生成的产物文件夹实际名称，将部署步骤的dist-folder参数修改为对应名称即可。
• 确认项目目录结构
  如果项目源码存放在仓库子目录（比如web/client文件夹下），根目录执行yarn build要么无法正常生成产物，要么生成的产物文件夹在子目录内，部署步骤默认查找仓库根目录下的build文件夹自然会报错。这种情况需要给依赖安装、项目构建步骤添加working-directory参数指定项目所在子路径，同时将dist-folder改为对应子目录下的产物路径，例如./client/build。
• 新增目录校验步骤明确产物位置
  可在构建步骤之后、部署步骤之前新增日志打印步骤，直接输出当前工作目录的文件结构，快速确认产物实际位置：

  - name: Verify build output
    if: ${{ steps.project.outputs.deployment-enabled == 'true' }}
    run: |
      ls -la
      # 若怀疑产物在子目录，追加执行 ls -la 对应子目录路径
  

  重新运行工作流后查看该步骤的输出日志，就能明确构建完成后当前目录的文件结构、产物文件夹的实际名称和路径。
• 检查构建脚本执行逻辑
  部分项目的构建脚本可能存在配置问题：比如必需的环境变量缺失时，脚本没有抛出非0退出码，导致CI判定步骤执行成功，但实际并未生成完整产物。可以查看构建步骤的完整执行日志，确认是否有"Build complete"、"Compiled successfully"这类明确的构建成功提示，同时核对日志中打印的产物输出路径，和配置中dist-folder的值是否匹配。
• 排除特殊文件类型问题
  IONOS部署动作默认无法识别软链接形式的目录，如果构建脚本生成的产物目录是软链接而非实体文件夹，也会报目录不存在的错误，可以通过上述目录校验步骤的日志确认文件夹类型。

内容的提问来源于stack exchange，提问作者Bikas Lin