大家好我是 SiKi老师。资源清单里明明写着textures\hero.png检查脚本却说“缺文件”你打开文件夹一看图片好好地躺在那儿。一份清单五行脚本报缺五个最后真缺的只有一个。先说结论先别急着报缺先把“从哪里找”和“路径怎么写”对齐以清单所在目录为根去掉首尾空白统一斜杠再单独看大小写剩下找不到的才是真缺。本文在 Linux 上的 Python 3.12.15 中运行另用 3.13.5 复跑同一脚本下面引用的输出两边一致。清单和文件全部自拟只放在临时目录里不读写真实项目。官方在线文档页面标注的小版本是 3.12.16与本机安装的 3.12.15 差一个补丁号正文以本机实测为准。Windows 和 macOS 未实测涉及它们的地方我会写明是教学说明。一 先复现五行清单脚本报缺五个自拟磁盘上的资源都在assets目录下assets/textures/hero.png assets/audio/bgm.ogg assets/ui/btn.png assets/ui/Icon.png assets/manifest.txt清单assets/manifest.txt是不同同事手写或从不同工具导出的五行写法各不一样MANIFEST[textures\\hero.png,# 在 Windows 上写的反斜杠./audio/bgm.ogg,# 开头多了 ./ui/btn.png ,# 末尾多了一个空格ui/icon.png,# 磁盘上是 Icon.pngfx/boom.png,# 真的没有]新手最常见的第一版检查是直接Path(行).exists()。脚本放在tools目录里运行时本地结果是5 行全部报缺。原因很简单相对路径是相对“当前工作目录”找的而当前目录是tools不是清单所在的assets。二 第一步以清单所在目录为根清单里的相对路径本意是“相对清单自己”。所以先把根定下来frompathlibimportPath manifestbase/manifest.txt# base 就是 assets 目录entriesmanifest.read_text(encodingutf-8).splitlines()missing[eforeinentriesifnot(base/e).exists()]本地这次报缺变成 4 个[textures\\hero.png, ui/btn.png , ui/icon.png, fx/boom.png]./audio/bgm.ogg已经能找到了。官方 pathlib 文档写明多余的斜杠和单个点会被合并掉所以./audio/bgm.ogg和audio/bgm.ogg是同一个路径但两个点..不会被合并本地PurePosixPath(audio/../audio/bgm.ogg)打印出来仍保留..。剩下 4 个还要继续排查。三 第二步去掉空白、统一斜杠末尾空格肉眼几乎看不出来但它是文件名的一部分ui/btn.png 和ui/btn.png是两个不同的名字。读清单时先strip()。反斜杠更隐蔽。在 Linux 上反斜杠不是路径分隔符本地打印frompathlibimportPurePosixPath,PureWindowsPathprint(repr(PurePosixPath(textures\\hero.png).name))# textures\\hero.pngprint(PureWindowsPath(textures\\hero.png).as_posix())# textures/hero.png第一行说明 Linux 把整串当成一个文件名当然找不到。官方文档说明PureWindowsPath按 Windows 规则理解路径并且这些“纯路径”类在任何系统上都能创建、不访问磁盘as_posix()会返回用正斜杠/表示的字符串。于是规范化函数可以这样写defnormalize(entry:str)-str:returnPureWindowsPath(entry.strip()).as_posix()按规范化后的写法再查hero.png、bgm.ogg、btn.png三个都找到了。注意这一招默认清单里的反斜杠都是“分隔符”如果你的项目真有文件名里带反斜杠就不能这样处理。四 第三步大小写单独报不要混进“缺失”剩下ui/icon.png和fx/boom.png。本机 Linux 临时目录区分大小写icon.png找不到Icon.png。官方文档也写明PurePosixPath(foo) PurePosixPath(FOO)为假PureWindowsPath的同样比较为真。Windows 上常见的磁盘默认不区分大小写可能“在我电脑上能找到”换到区分大小写的环境就不行了这句是教学说明本文未在 Windows 实测。所以我把磁盘上的实际文件先列出来用casefold()做一张对照表只用来提示大小写不一致disk_rel[p.relative_to(base).as_posix()forpinbase.rglob(*)ifp.is_file()]by_fold{}forrelindisk_rel:by_fold.setdefault(rel.casefold(),[]).append(rel)found,rewritten,case_only,missing[],[],[],[]forrawinentries:normnormalize(raw)if(base/norm).is_file():found.append(norm)ifnorm!raw:rewritten.append((raw,norm))elifnorm.casefold()inby_fold:case_only.append((raw,by_fold[norm.casefold()]))else:missing.append(raw)本地最终报告found [textures/hero.png, audio/bgm.ogg, ui/btn.png] rewritten [(textures\\hero.png, textures/hero.png), (./audio/bgm.ogg, audio/bgm.ogg), (ui/btn.png , ui/btn.png)] case_only [(ui/icon.png, [ui/Icon.png])] missing [fx/boom.png]五行里只有fx/boom.png是真缺三行是“写法不统一但能找到”一行是“大小写对不上”。这三类要分开交给人处理而不是一句“缺 5 个文件”。脚本最后检查清单内容和读取前一致本地manifest_untouched True只报告不自动改清单、不自动改文件名。五 一步步排查清单先确定根目录清单里的相对路径以清单所在目录为根不靠当前工作目录碰运气。每行先strip()去掉首尾空格和换行残留。统一斜杠用PureWindowsPath(行).as_posix()把反斜杠转成/单个点会被合并。规范化后还找不到再用casefold()对照磁盘清单把“只差大小写”单独列出来。剩下的才报“真缺失”报告分三类给人确认修清单或改文件名留到下一步不在检查脚本里顺手改。本次独立验证脚本覆盖了上面每一条在 3.12.15 和 3.13.5 上都通过。未测试 Windows/macOS 文件系统、网络路径和符号链接..越出根目录这类安全边界也不在本文范围。你的资源清单里最常见的是哪一种“写法不一样”可以贴一行自拟的清单路径和报错说说你最后是怎么对上的。依据Python 3.12 官方文档 pathlib 页docs.python.org/3.12/library/pathlib.html关于纯路径类、斜杠与单点合并、大小写比较规则、as_posix、exists 与 rglob 的说明。示例和表达原创不引用具体课程信息。
