AI 说文件不存在，可它明明就在那里：四种成因的排查顺序

2026-07-28

数据截至 2026-07，各产品的额度与报错口径以官方最新说明为准。

这类问题里真正的成因几乎从来不是模型幻觉，而是 AI 工具看到的那份文件系统视图，和你在编辑器里看到的不是同一份。 大多数人第一反应是”模型不行、又开始编了”，于是换模型、换措辞、把文件内容整段贴进对话框绕过去。绕得过一次，第二天换个文件又来一遍。你把它当成模型能力问题，就永远只能靠贴内容硬扛；把它当成路径解析问题，十分钟就能定位到具体是哪一层把这个文件挡掉了。

先接受一个前提：AI 编码工具读文件不是玄学，它最终也是发起一次普通的文件读取。中间可能隔着工作目录基准、路径归一化、忽略规则过滤、权限沙箱这几层，任何一层做了和你预期不同的事，结果都是那句干巴巴的”文件不存在”。排查的全部工作，就是从外到内把这几层逐个证伪。

一、先把”读不到”分成三类，别一上来就改代码

同样一句”我没找到这个文件”，背后其实是三种完全不同的故障，混在一起排查必然乱。

第一类是硬失败。 你给了明确路径，工具尝试读取并明确回报路径不存在、无法访问、目录不存在。特征是它复述了一个具体路径，而且这个路径通常和你想的略有出入。这类是确定性的，一定能复现，一定有唯一成因，也就是这篇要处理的对象。

第二类是软失败。 你没给路径，只说了”改一下登录逻辑”，工具搜了一圈说没找到相关文件。这不是读不到，是检索没命中：仓库太大、索引没覆盖、关键词对不上、上下文塞不下。它读得到，只是不知道该读哪个。

第三类是读到了但内容是旧的。 工具复述的代码和你屏幕上的对不上，行号也差几行。这是缓存或索引陈旧，不是不存在。

这篇只管第一类。第二类里因为多包结构导致工具在错误的包里打转，属于结构性误判，另开一篇讲过monorepo 里 AI 认错包、改错目录的迷惑行为；因为仓库体量导致相关文件根本进不了视野的，则是大仓库上下文不足那一套治法。三者的处置动作完全不同：硬失败靠改路径和配置，一次性解决；软失败靠拆范围和给锚点，是长期工程。分诊错了，你会拿着治软失败的手段去打硬失败，越治越乱。

分诊只需要一步：让工具原样复述它尝试访问的绝对路径。它复述得出来，就是硬失败，往下走；它复述不出来、只说”没搜到”，去看那两篇。

二、四种成因的判别表

硬失败的成因高度集中。下面这张表按我实际处理的频次从高到低排，照着从上往下试，绝大多数情况在前两行就结束了。

现象	大概率成因	怎么验证	处置动作
工具复述的绝对路径里，仓库根之后的部分多了一层或少了一层	会话工作目录和你以为的不同	让它执行 `pwd`，和你终端里的 `pwd` 对比	它的 `pwd` 就是仓库根 → 统一改用相对仓库根的完整路径；不是仓库根 → 在仓库根重启会话，或直接给绝对路径
路径完全对，但只有部分文件读不到；换个同目录文件就正常	文件名大小写不符	`find . -iname "目标文件名"` 看真实拼写	按真实拼写引用；若是仓库里两份大小写不同的同名文件，先修仓库
目标是 `node_modules`、`packages` 下的跨包路径，或路径中某段指向别处	符号链接，多数工具不跟随指向根目录之外的链接（各产品策略不同）	`ls -l` 看是否有 `->`，或用 `os.path.realpath` 取真实路径	直接给链接解析后的真实绝对路径
构建产物、日志、`dist`、`.env` 之类读不到，源码全正常	命中忽略规则被过滤	`git check-ignore -v -- 路径` 看是哪条规则	临时复制一份到未被忽略的位置，或按产品说明放开该目录
报的不是”不存在”而是无权访问、操作被拒	权限或沙箱策略拦截	用同一身份在终端里 `cat` 一下能不能读	见沙箱权限拒绝的排查，不在本篇范围
文件是刚创建的，工具反复说不存在	编辑器缓冲区没落盘，或写在了另一个 worktree	`ls -l` 看文件是否真的存在、`git worktree list` 看有几个工作树	保存落盘；确认你和它在同一个工作树里

前四行是这篇要展开的四种成因，后两行是边界情况，列在这里是为了让你能尽早把它们排除掉。区别在于：权限那一行有个明显的分水岭——报错措辞是”无权访问、操作被拒”而不是”不存在”，看到这个词就直接转去权限那条线，别在路径上耗；未落盘和多工作树那一行则相反，它的表象和前四行完全一致，同样是干巴巴一句”不存在”，只能靠 ls -l 和 git worktree list 两条命令去区分，所以真遇上时最费时间。

三、逐条验证与处置

1. 工作目录不一致

这是第一位的成因，尤其在你从子目录启动会话、或者编辑器打开的是多根工作区的时候。两边的基准不是同一个目录，同一串相对路径就指向两个地方。

举个最常见的形态：你的终端 cd 在 packages/web 里，顺口说”看下 src/api/user.ts”；会话是在仓库根启动的，它把这串拼成仓库根下的 src/api/user.ts，而仓库根下压根没有 src 这一层，于是如实回你不存在。反过来也一样：会话起在 packages/web，你按仓库根的习惯说 packages/web/src/api/user.ts，它拼出 packages/web/packages/web/src/api/user.ts。判断方向就看它复述的路径是多了一层还是少了一层——多一层是它的基准比你深，少一层是比你浅。

验证只要一条命令，让它自己执行：

pwd && ls -la | head -20

把输出和你终端里同样命令的输出对一下。基准不同就立刻暴露。顺带说一句，你在终端里 cd 过去，不代表 AI 会话的工作目录跟着变——它们是两个进程，各有各的 cwd。

处置有两种，但要先看清一个前提：“用相对仓库根的完整路径”只有在工具的 cwd 确实等于仓库根时才成立。 上一步 pwd 的输出如果就是仓库根，那么从此统一写 packages/web/src/api/user.ts 而不是 src/api/user.ts，多打十几个字符换一劳永逸；如果 pwd 指向的是某个子目录，相对仓库根的路径照样会被拼错，这时候要么在仓库根重启会话把基准拉齐，要么干脆给绝对路径。绝对路径最笨也最不会错，代价是不方便跨机器复述，所以我只在基准对不齐、又暂时不想重启会话时用它。

多根工作区的情况下，别指望工具自动猜出你说的是哪个根，明确写出包名那一段。

2. 文件名大小写

这条最阴，因为它在你本机可能永远不发作。macOS 和 Windows 的默认文件系统不区分大小写，Linux 的常见文件系统区分。你本地写 Utils.ts 引用 utils.ts 一切正常，可一旦代码跑进 Linux 容器，或者工具不是直接发起读取、而是拿路径去和自己维护的那份文件清单做字符串比对，就当场炸。

这里要分清两层，否则你在 macOS 上会觉得判别表这一行根本不成立。操作系统那一层，不区分大小写的文件系统会替你把 utils.ts 兜到 Utils.ts 上，读取照样成功；工具那一层如果先在自己的索引或目录列表里做精确匹配，匹配不上就直接回你”不存在”，压根走不到读取那一步。所以”我在终端里 cat 得出来、它却说没有”这个组合，恰恰是大小写这条线最典型的指纹。反过来，如果你自己 cat 也读不到，那多半不是大小写，是路径本身就错了，回第一条查工作目录。

先看真实拼写：

find . -iname "utils.ts" -not -path "*/node_modules/*"

-iname 是大小写无关匹配，它列出来的是磁盘上的真实名字。如果它列出的和你引用的对不上，成因就确定了。

再看仓库层面有没有更深的坑：

git config --get core.ignorecase
git ls-files | tr 'A-Z' 'a-z' | sort | uniq -d

第二条把所有跟踪文件名转小写后找重复，能揪出仓库里存在两份仅大小写不同的同名文件——这种仓库在不区分大小写的系统上 clone 出来会互相覆盖，是隐性事故源。第一条查的是 core.ignorecase：在不区分大小写的文件系统上初始化或克隆时，git 通常会自己把它置成 true，这也是为什么本机改大小写常常”改了跟没改一样”。这条命令没有输出只说明该项没被显式写进配置，不等于它是 false，判断实际行为还是以文件系统本身为准。修的时候别直接 git mv Utils.ts utils.ts——底层文件系统认为源和目标是同一个东西，这条命令要么报目标已存在，要么执行完索引里的名字纹丝不动。走两步中转：

git mv Utils.ts utils.tmp
git mv utils.tmp utils.ts

顺手说个变种：文件名里的不可见字符和中文的 Unicode 归一化差异。macOS 上创建的含中文文件名可能以分解形式（NFD）存储，你从别处复制粘贴过来的是合成形式（NFC），肉眼一模一样，字节不同，匹配自然失败。检查方法：

python3 -c "import os,unicodedata as u; [print(repr(n), n==u.normalize('NFC',n)) for n in os.listdir('.')]"

输出里 False 的那些就是分解形式。文件名末尾多个空格也是同类问题，repr 一律现原形。

3. 符号链接与工作树

包管理器普遍用符号链接做依赖复用和工作区互链，仓库里也常有人手工建链接指向共享配置。AI 工具出于安全考虑，通常不跟随指向工作目录之外的链接——我认为这是合理的默认，因为跟随了就等于凭一个链接把整块磁盘暴露给了会话。代价是你会遇到一个”路径明明列得出来却读不了”的怪现象。

判断链接和它的真实落点：

ls -l packages/shared
python3 -c "import os,sys; p=sys.argv[1]; print('abs :',os.path.abspath(p)); print('link:',os.path.islink(p)); print('real:',os.path.realpath(p)); print('ok  :',os.path.exists(p))" packages/shared

ls -l 里带 -> 就是链接。realpath 给出的才是工具最终要访问的位置，如果这个位置跳出了仓库根，读不到是预期行为，不是 bug。处置就是直接把真实绝对路径给它，或者把需要它看的那部分内容以真实路径纳入会话范围。

工作树是同一类问题的另一种表现。你在 git worktree 开出来的分支目录里改文件，会话却起在主工作树上，两边同名文件内容不同、甚至一边压根没有。先确认有几个：

git worktree list

输出里每行是一个工作树的路径和它当前所在的分支。拿这些路径和上一步 pwd 的结果比一比，对不上就说明你俩在两棵树上——那个文件确实不存在于它那一侧，它没编。处置有两条：要么把会话重开在你正在改的那棵树的目录里，要么把改动提交后在它那侧取到。别试图用相对路径把它”引”过去，跨工作树的相对路径只会解析到另一棵树里的同名文件上，读得到但内容不是你要的那份，比读不到更难查。

4. 被忽略规则挡住

多数 AI 编码工具默认沿用仓库的忽略规则来决定哪些文件不进视野，是否可以放开、怎么放开，各产品做法不同且会调整，以官方最新说明为准。这个默认本身是对的：没人希望它去读 node_modules 和构建产物。麻烦出在你确实需要它看 dist 里的某个产物，或者看一份被忽略的本地配置样例。

定位是哪条规则干的：

git check-ignore -v -- dist/types/index.d.ts

有输出就说明命中了，输出里会写明是哪个文件的第几行规则。要注意三件事。一是 check-ignore 只对未跟踪文件有意义，已被 git 跟踪的文件即使匹配规则也不会被忽略。二是规则可能来自三处：仓库内各级 .gitignore、.git/info/exclude、以及全局配置，全局的位置用 git config --get core.excludesFile 查。三是 git 有个硬性语义——父目录整体被忽略时，用 ! 单独放行子文件是无效的。这条经常让人以为自己写的 ! 规则失灵：

# 无效写法：父目录已整体排除，子文件放行不生效
dist/
!dist/types/index.d.ts

# 有效写法：先只排除目录内容，再放行具体文件
dist/*
!dist/types/
!dist/types/index.d.ts

处置上，最省心的是把需要它读的那份文件复制到一个未被忽略的临时目录，用完删掉。改忽略规则或调工具配置放开整个目录，收益不大，风险是把一堆噪声连同密钥文件一起推进会话，这笔账不划算。密钥类文件更该老老实实隔离在会话视野之外。

四、什么情况下别再折腾

有止损点，否则这类问题能吃掉你一下午。

三轮之内没定位到成因，就停手换路。 三轮指的是完整跑一遍工作目录、大小写、链接这三项验证。三项都排除，说明成因不在常见清单里，继续用同样的方式猜下去边际收益趋近于零。这时候把文件内容直接贴进对话，把当前这件事做完，故障留到手头任务结束后单独查。别在赶工的路上做根因分析。

工具连自己的工作目录都复述不出来，直接重启会话。 这通常意味着会话状态已经乱了，继续问只会得到越来越离谱的回答。重启的成本远低于纠缠的成本。

同一个路径它前面读过、现在读不到，先怀疑文件真的没了。 尤其是这中间它执行过移动、重命名或清理动作。先 git status 看工作区，必要时从暂存区或最近一次提交里取回。这种情况下继续追问路径，方向从一开始就错了。

本机全对但只在容器或 CI 里失败，问题不在 AI，在环境差异。 大小写敏感性、挂载点、卷映射范围都会造成同样的现象，这属于运行环境不一致的范畴，得去那一层查，在会话里反复试是白费。

回滚点也要提前想好。 为了让工具读到某个文件而去改忽略规则、改工具配置、改链接结构的，动手前记一笔改了什么。这类改动最容易忘，忘了之后下次别人 clone 仓库会遇到你留下的怪行为。改忽略规则的那次提交单独提，别混进业务改动里。

五、避坑清单

别把”读不到”当模型能力问题，去换模型。 会踩是因为报错文本读起来像模型在胡说，人的直觉是换个聪明点的。但路径解析这层和模型无关，换任何模型结果都一样。避法：看它有没有复述具体路径，复述得出来就说明它老实执行了读取，问题在路径本身。

别用相对路径跟它沟通。 会踩是因为你在终端里习惯了相对路径，顺手就写。它的基准和你的终端基准不是一回事，同一串字符指向两个地方。避法：涉及文件的每一句话，一律给相对仓库根的完整路径。多打的那几个字符是最便宜的保险。

别在不区分大小写的机器上信任”本地能跑”。 会踩是因为本机把 Utils.ts 和 utils.ts 当同一个文件，错误被系统悄悄兜住了。避法：把大小写重名检查加进 CI，一行 shell 就够，比在生产事故里发现便宜得多。

别为了一次读取就永久放开忽略规则。 会踩是因为当下觉得改一行最快。后果是从此每次会话都被构建产物和日志灌满，还可能把 .env 一类的东西带进去。避法：临时复制到未忽略目录，用完删。

别忘了保存。 会踩是因为编辑器里内容看着好好的，你完全意识不到它还在缓冲区。避法：报”不存在”时的第一个动作，是切到终端 ls -l 看文件真实存在与否和修改时间，而不是继续追问。

别在多工作树的仓库里凭记忆判断自己在哪。 会踩是因为几个工作树目录名相似、分支不同，切换频繁时人很容易记错。避法：git worktree list 加 git branch --show-current 两条命令，五秒钟消除全部歧义。

别忽略”只有部分文件读不到”这个信号。 会踩是因为它像随机故障，让人往玄学方向想。实际上部分失败几乎必然指向大小写或链接，全部失败才指向工作目录或权限。避法：读不到时顺手试同目录的另一个文件，这一步的信息量比任何追问都大。

编辑器索引失效会伪装成读不到。 会踩是因为索引层报的错和文件系统层报的错在措辞上很接近。避法：看它是在”搜索”还是在”读取指定路径”，前者失败属于索引问题，处置见编辑器索引失败的排查。

六、收尾

这类故障的价值在于它是确定性的：有唯一成因，能被证伪，十分钟内必有结论。真正浪费时间的从来不是排查本身，而是一开始就归错了因，把一个路径问题当成了模型问题。

留一张自检清单，下次撞上按顺序过一遍：

让它复述尝试访问的绝对路径。复述不出来 → 这是检索问题，不是本篇的问题。
让它执行 pwd，和你的终端对比。不一致 → 改用相对仓库根的完整路径。
试读同目录另一个文件。别的能读 → 查大小写和符号链接；都读不到 → 查工作目录和权限。
find . -iname 确认真实拼写，ls -l 确认有没有 ->。
git check-ignore -v -- 路径 确认是否命中忽略规则。
ls -l 确认文件真的在磁盘上、修改时间对得上；git worktree list 确认你俩在同一个工作树。
三轮无果就止损：贴内容把活干完，故障单独立项。