Bitbucket Pipelines部署dist至FTP失败：文件路径不存在问题排查

一、先解决找不到dist路径的错误 #

1. 确认构建步骤真的生成了dist文件夹
   你在Build project步骤里配置了artifacts: - dist/**，但得先确保npm run build确实在项目根目录生成了dist文件夹。直接在Build步骤的script里加一句验证命令：

- ls -la dist/

如果这步输出为空，说明问题不在Pipeline，是前端构建命令没生成文件，得先排查npm build的逻辑。

2. 修正LOCAL_PATH的写法
   别用dist/*，直接写dist/即可。atlassian/ftp-deploy管道的LOCAL_PATH是指定要上传的目录，dist/会把整个目录下的内容（包括子文件夹）全部上传，而dist/*会因为shell通配符的问题导致路径识别失败。修改后的变量：

LOCAL_PATH: 'dist/'

3. 验证Deploy步骤能获取到dist文件
   跨步骤的artifacts可能出现传递异常，在Deploy步骤开头加一句确认：

- ls -la /opt/atlassian/pipelines/agent/build/dist/

如果这步看不到文件，说明artifacts没传递成功，得检查Build步骤的artifacts配置是否有误。

二、验证Pipeline与FTP服务器的连通性 #

在Deploy步骤里先手动测试FTP连通性，用lftp工具（node镜像默认未安装，需先安装）：

script:
  - apt-get update && apt-get install -y lftp
  - lftp -e "ls; quit" -u $FTP_USERNAME,$FTP_PASSWORD $FTP_HOST

如果这步能成功列出FTP根目录内容，说明账号、地址、密码均正确且网络连通；如果报错，先检查FTP配置信息，再确认服务器防火墙是否允许Bitbucket Pipelines的IP段访问（可将Bitbucket官方公布的IP段添加到FTP服务器白名单）。

三、正确替换FTP服务器上的dist文件夹文件 #

1. 添加--delete参数清理旧文件
   在EXTRA_ARGS里加入--delete，这样会删除FTP服务器目标路径中与本地dist不一致的文件，实现完全替换：

EXTRA_ARGS: "--exclude=.bitbucket/ --exclude=.git/ --exclude=bitbucket-pipelines.yml --exclude=.gitignore --delete"

注意：该操作会删除服务器上不在本地dist中的文件，执行前请备份好服务器现有文件。

2. 确认REMOTE_PATH路径存在且有权限
   你配置的'/var/www/*******/booking.crt-minds.ru/'必须是FTP服务器上真实存在的路径，且你的FTP用户拥有该路径的读写权限。用以下命令验证：

- lftp -e "ls /var/www/*******/booking.crt-minds.ru/; quit" -u $FTP_USERNAME,$FTP_PASSWORD $FTP_HOST

修正后的完整bitbucket.yml示例 #

image: node:16

pipelines:
  branches:
    master:
      - step:
          name: Install dependencies
          caches:
            - node
          script:
            - npm install
          artifacts:
            - node_modules/**
      - step:
          name: Build project
          caches:
            - node
          script:
            - npm run build
            - ls -la dist/  # 确认dist生成
          artifacts:
            - dist/**
      - step:
          name: Deploy to Production
          trigger: manual
          deployment: Production
          script:
            - apt-get update && apt-get install -y lftp
            - lftp -e "ls /var/www/*******/booking.crt-minds.ru/; quit" -u $FTP_USERNAME,$FTP_PASSWORD $FTP_HOST  # 验证FTP路径和连通性
            - ls -la dist/  # 再次确认dist存在
            - pipe: atlassian/ftp-deploy:0.3.7
              variables:
                USER: $FTP_USERNAME
                PASSWORD: $FTP_PASSWORD
                SERVER: $FTP_HOST
                REMOTE_PATH: '/var/www/*******/booking.crt-minds.ru/'
                LOCAL_PATH: 'dist/'
                EXTRA_ARGS: "--exclude=.bitbucket/ --exclude=.git/ --exclude=bitbucket-pipelines.yml --exclude=.gitignore --delete"

内容的提问来源于stack exchange，提问作者Said Kamolov