GitLab Runner on Fargate异常：sfdx command not found

核心原因分析 #

本地运行镜像正常，但Fargate上GitLab Runner执行任务时找不到sfdx，大概率是环境变量PATH不包含sfdx的安装路径，或者任务执行的用户上下文与镜像构建/本地运行时不一致导致的。

具体排查步骤 #

1. 确认sfdx的实际安装路径
   在Dockerfile中添加一行构建命令，查看sfdx的安装位置：

   RUN which sfdx && ls -l $(which sfdx)
   

   重新构建镜像，输出结果会显示sfdx的绝对路径（比如/usr/local/bin/sfdx或/root/.npm-global/bin/sfdx）。

2. 验证任务执行时的PATH环境变量
   在CI任务中添加命令，查看当前的PATH：

   echo $PATH
   

   对比sfdx的安装路径，确认该路径是否在PATH列表中。

解决方法 #

方法1：在Dockerfile中固定PATH环境变量 #

根据第一步得到的sfdx路径，在Dockerfile中添加环境变量声明，确保所有用户上下文都能访问到：

# 替换成实际的sfdx路径
ENV PATH="/usr/local/bin:$PATH"

如果sfdx安装在用户目录（比如/root/.npm-global/bin），则修改为：

ENV PATH="/root/.npm-global/bin:$PATH"

方法2：确保ssh登录后的shell加载正确环境 #

因为你的entrypoint启动了sshd，GitLab Runner通过ssh连接执行任务，需要保证ssh登录后的shell能加载到正确的PATH：
在entrypoint.sh中添加一行，将sfdx路径写入全局profile：

# 替换成实际的sfdx路径所在目录
echo 'export PATH="/usr/local/bin:$PATH"' >> /etc/profile

方法3：临时用绝对路径执行命令验证 #

在CI脚本中先用绝对路径执行sfdx，确认命令本身可正常运行：

# 替换成实际的sfdx绝对路径
/usr/local/bin/sfdx --version

如果能正常输出版本，说明确实是PATH问题，再用方法1或2彻底解决。

方法4：统一任务执行用户 #

如果GitLab Runner用非root用户执行任务（比如默认的gitlab-runner用户），可以在Dockerfile中创建该用户并切换，同时确保npm全局安装路径对该用户可访问：

RUN useradd -m gitlab-runner
USER gitlab-runner
# 切换用户后重新安装sfdx，确保路径在该用户的PATH中
RUN npm install sfdx-cli --global --force

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