GitLab CI runner找不到文件但文件实际存在的异常如何排查解决

高频问题排查及对应解决方案 #

• 换行符格式不兼容（占这类问题的90%以上）
  基本都是脚本在Windows环境编辑保存为CRLF换行格式，上传到Linux执行环境后，系统识别文件名、脚本解释器时会把行尾的\r（回车符）识别为有效字符。用普通ls、echo打印路径看起来完全正常，但系统实际查找的是带不可见回车符的目标，自然提示不存在。
  排查命令：cat -v 你的脚本文件路径，如果每行末尾出现^M标记即可确认问题。
  解决方法：执行dos2unix 你的脚本文件直接转换格式；也可以在仓库配置.gitattributes强制所有.sh文件用LF换行，或者给git加全局配置git config --global core.autocrlf input，拉取代码时自动转换换行符。
• Shebang解释器配置错误
  绝大多数人会被报错误导：提示"找不到文件"很多时候不是指你的脚本本身，而是脚本第一行声明的解释器路径不存在。比如脚本开头写了#!/bin/bash，但你用的极简Docker镜像里bash实际安装在/usr/bin/bash，甚至根本没装bash；如果第一行末尾带不可见特殊字符，也会触发完全一样的报错。
  排查命令：head -1 你的脚本路径 | cat -v 查看第一行有没有多余特殊字符，再执行which sh && which bash 对比当前环境的解释器真实路径。
  解决方法：修正shebang为当前环境真实存在的解释器路径，通用适配写法可以用#!/usr/bin/env bash自动查找环境变量里的解释器路径。
• 路径/文件名带不可见字符
  如果路径里混入了全角空格、零宽空格、不可见控制字符，普通ls不会显示这些字符，肉眼看到的路径和系统实际识别的路径完全不一致。
  排查命令：执行ls -lb 脚本所在目录，这个参数会把所有不可见字符转成八进制编码打印，能直接看到文件名里藏的异常字符。
  解决方法：重命名文件去掉异常字符，执行脚本时给路径加双引号避免空格被shell拆分解析。
• 沙箱/软链接访问异常
  如果你是通过软链接访问的脚本，普通ls只能看到软链接文件本身存在，但如果软链接指向的真实路径不在Runner的沙箱挂载范围内（比如Docker/K8s executor没挂载软链接对应的宿主机目录），访问真实文件内容时就会提示不存在。
  排查命令：执行file 你的脚本路径，如果输出显示broken symbolic link即可确认。
  解决方法：直接用文件的真实绝对路径执行，或者在Runner配置里把软链接对应的真实目录加入挂载白名单。
• 执行上下文路径偏差
  如果你的执行逻辑里提前写了cd切换目录的命令，一旦切目录执行失败（比如目录名拼写错误、权限不足），后续用相对路径调用脚本时就会找错位置；另外不同job step的工作目录如果没配置持久化，前一步生成的文件在后一步也会不存在。
  排查方法：在执行脚本的命令前加两行调试逻辑：pwd && ls -l 脚本的绝对路径，确认当前工作目录、文件真实路径和你写的执行路径完全一致。
  解决方法：调用脚本时统一用绝对路径，不要依赖相对路径；跨step传文件要配置正确的缓存/制品规则。

现场报错参考 #

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