Gemini CLI 的 write_file 报 "ENAMETOOLONG: name too long"：如何解决

你升级了 Gemini CLI，让智能体创建或编辑一个文件名很长的文件，结果 write_file（或 replace）返回 ENAMETOOLONG: name too long。文件名本身是合法的：用 shell 写同一个文件毫无问题。真正超出限制的，是 Gemini CLI 从 0.64.0（当前稳定版）开始创建的临时文件。

本文说明这个错误从哪里来、如何用一条命令确认，以及在官方修复发布前的三种解决办法。所有内容均于 2026年10月17日 对照 google-gemini/gemini-cli 仓库的源代码和发布记录核对，并在 ext4 文件系统上复现了该限制。

Gemini CLI 的 write_file 报 "ENAMETOOLONG" 是什么意思？

意思是操作系统拒绝打开一个文件名超过 255 字节的文件。关键在消息末尾：被拒绝的路径以 .tmp 结尾，并不是你要写的那个文件。

Error writing to file '/project/docs/<long-name>.md': ENAMETOOLONG: name too long, open '/project/docs/<long-name>.md.8dcae82f-0430-47ee-adf0-bcd8979a3a72.tmp' (ENAMETOOLONG)

文件不会被创建。如果文件已经存在，智能体既不能覆盖也不能编辑它。这个问题记录在 2026年10月10日 提交的 issue #29702 中。

为什么合法的文件名在 0.64.0 中会出错？

因为 0.64.0 改成了原子写入：先写入目标旁边的临时文件，再重命名。临时文件名是目标文件名加上一个 UUID 和 .tmp，多出 41 字节。代码位于 packages/core/src/services/fileSystemService.ts：

const tmpPath = `${realPath}.${randomUUID()}.tmp`;

Linux 和 macOS 的单个文件名最多 255 字节（NAME_MAX）。所以 215 到 255 字节之间的文件名对系统是合法的，对临时文件却是非法的。在 ext4 上测试：214 字节的文件名生成 255 字节的临时文件名，写入成功；215 字节时临时文件名达到 256 字节，写入失败。

版本	写入方式	发布日期
0.63.0	直接写入目标，不使用临时文件	2026年10月6日
0.64.0（稳定版，latest 标签）	临时文件加重命名，超过 214 字节即失败	2026年10月13日
0.65.0-preview.0 及 10月17日 的 0.66.0 nightly	与 0.64.0 代码相同	2026年10月13日 至 10月17日

按字节计算，而不是按字符

在 UTF-8 中，普通英文字母占 1 字节，带重音的字母占 2 字节，中文或日文字符占 3 字节。70 个汉字加 .md 的文件名是 213 字节，可以写入；71 个汉字就是 216 字节，write_file 会失败。用文档标题、长 slug 或内嵌哈希生成的文件名很容易超限。

用符号链接绕开也不行：Gemini CLI 在拼接临时文件名之前会把链接解析成真实路径，所以计算的是目标文件自己的名字。

如何确认是这个问题？

查看版本，并按字节计算文件名长度：

gemini --version
printf '%s' 'file-name.md' | wc -c

如果版本是 0.64.0 或更新，并且数字超过 214，就是这个 bug。要一次找出项目里所有 write_file 无法重写的文件：

find . -type f | LC_ALL=C awk -F/ 'length($NF) > 214'

LC_ALL=C 让 awk 按字节而不是按字符计数。文件系统的上限可以用 getconf NAME_MAX . 查看（ext4、APFS 及大多数环境为 255）。

如何解决 Gemini CLI 的 ENAMETOOLONG？

把文件名缩短到 214 字节以内。这是最简单的办法，也不受版本影响。为了让智能体不再生成长文件名，把规则写进项目的 GEMINI.md：

新文件名：最多 150 字节。使用简短的 slug，不要用完整标题。

需要编辑一个已有的长文件名文件

先改名，编辑后再改回原名。mv 不使用临时文件，所以只要系统接受的文件名都能用：

mv 'original-long-name.md' tmp-edit.md
# 让智能体编辑 tmp-edit.md
mv tmp-edit.md 'original-long-name.md'

另一个办法是让智能体通过 shell（run_shell_command）写入，而不是用 write_file。shell 直接写入目标文件，不会加上 41 字节的后缀。

文件名不能改：退回 0.63.0

1. 在 ~/.gemini/settings.json 中关闭自动更新，否则 Gemini CLI 会自己升回 0.64.0：

   {
     "general": {
       "enableAutoUpdate": false
     }
   }

2. 安装上一个版本：

   npm install -g @google/gemini-cli@0.63.0

注意取舍：0.63.0 在 YOLO 模式下有 Untrusted Command Flags Detected 误报，这个问题在 0.64.0 中已修复。我们在这篇指南中讲过这个警告。如果你使用 --yolo 运行，缩短文件名通常比降级更省事。

官方修复什么时候发布？

目前还没有。2026年10月10日 提交的 PR #29703 让临时文件仍留在同一目录（保证重命名依然是原子操作），并截短临时文件名使其不超过 255 字节，同时为 254 字节的 ASCII 文件名和长中文文件名加了测试。截至 10月17日，该 PR 仍未合并。请关注 issue #29702，等修复进入稳定版后，再重新打开 enableAutoUpdate。