最近在将一个 iOS 工程升级到 Xcode 26.5 时，Xcode 抛出了这样一个报错：
The project item “ABcD.xcodeproj/Example for ABCD”
refers to the path “ABCD”,
but the capitalization on disk is “ABcD”.
Rename one of them to make them match.
乍一看很奇怪：
Xcode 明明提示路径大小写不一致，但项目仍然可以正常运行。
这篇文章主要总结一下这个问题的现象、根因、潜在风险，以及在 Git 仓库中应该如何安全修复。
问题现象
报错信息的核心含义是：
Xcode 工程文件中记录的路径，与磁盘上的真实目录名不一致，通常是大小写不同。
例如，Xcode 工程里引用的是：
ABCD
但磁盘上的真实目录名是：
ABcD
由于两者大小写不完全一致，Xcode 会认为工程引用路径和磁盘实际路径不匹配，因此给出警告或错误提示。
为什么有报错但项目还能运行？
原因通常和 macOS 的文件系统有关。大多数 macOS 默认磁盘格式是：大小写不敏感，但大小写保留
这意味着：
ABCD
ABcD
abcd
在文件查找时，通常会被系统认为是同一个路径。
所以即使 Xcode 工程里引用的是 ABCD，而磁盘上的真实目录名是 ABcD，系统仍然可能找到对应文件，项目也就可以继续编译或运行。
但是，Xcode 会额外检查路径的真实大小写，因此会提示：
你引用的路径大小写和磁盘上的路径大小写不一致。
也就是说：
项目能运行，不代表路径配置是完全正确的。
导致这个问题的常见原因
这个问题很常见的一个触发方式是：
在 Finder 里面直接修改了 Git 仓库中文件或目录名的大小写。
在 macOS 上，Git 通常会有如下配置：
git config --get core.ignorecase
如果输出是：
true
就表示 Git 会忽略路径大小写差异。
这种情况下，如果你直接在 Finder 中把目录名从：
ABCD
改成：
ABcD
可能会出现这样的情况：
git status
没有任何变化。这就比较危险了。因为此时：
- Finder 里看起来已经改成功了；
- 本机 Xcode 可能也暂时不报错了；
- 但 Git 并没有记录这次大小写变更；
- 其他同事拉代码后，目录名可能仍然是旧的；
- CI 或其他机器上的 Xcode 仍然可能继续报错。
最终就会导致：
磁盘路径、Git index、Xcode 工程引用三者之间出现大小写不一致。
如何修复这种问题？
如果这是 Git 仓库里的目录，不建议直接用 Finder 修改大小写。
推荐使用：
git mv
并且最好采用“两段式重命名”。
因为在大小写不敏感的文件系统上，直接执行：
git mv ABCD ABcD
有时可能不会被 Git 正确识别。更稳妥的方式是先改成一个临时名字，再改成目标名字：
git mv ABCD ABCD_tmp
git mv ABCD_tmp ABcD
这样 Git 一定能识别到这是一次路径变更。
如果是 Xcode 工程目录、workspace 或 scheme 文件，也建议使用同样方式处理：
git mv ABcD.xcodeproj ABcD_tmp.xcodeproj
git mv ABcD_tmp.xcodeproj ABCD.xcodeproj
修复后需要检查哪些地方？
只改磁盘目录通常是不够的，还需要同步检查 Xcode 工程和相关配置文件。
常见需要检查的位置包括：
*.xcodeproj/project.pbxproj
*.xcworkspace/contents.xcworkspacedata
*.xcscheme
Podfile
*.podspec
fastlane/Fastfile
CI 配置文件
README.md
可以使用下面命令搜索旧命名是否仍然存在：
git grep -n -I 'ABcD'
也可以检查 Git 跟踪路径中是否还有旧大小写：
git ls-files | grep 'ABcD'
如果想检查磁盘上是否还有旧路径，可以使用：
find . -name '*ABcD*' -print
修复完成后，理想状态是：
- Git 跟踪路径中没有旧命名；
- 文件内容中没有旧命名；
- 磁盘目录名和 Xcode 工程引用完全一致；
- Xcode 重新打开后不再报路径大小写问题。
**修复后的验证方式
建议至少做以下几步验证。
- 检查旧路径是否清理干净
git ls-files | grep 'ABcD'
如果没有输出，说明 Git 跟踪路径里已经没有旧命名。
继续检查文件内容：
git grep -n -I 'ABcD'
如果也没有输出，说明工程配置和脚本里的旧引用基本已经清理干净。 - 检查 Xcode 是否能识别 workspace 和 scheme
例如：
xcodebuild -list -workspace Example/ABCD.xcworkspace
确认输出里能看到正确的 scheme。 - 执行一次构建验证
例如：
xcodebuild build \
-workspace Example/ABCD.xcworkspace \
-scheme ABCD-Example \
-destination 'generic/platform=iOS' \
CODE_SIGNING_ALLOWED=NO
如果最终看到：
** BUILD SUCCEEDED **
说明工程引用路径至少已经可以被 Xcode 正确解析。
这次问题带来的两个额外发现
这次修复大小写问题时，还顺带解决了两个之前困扰很久的问题。
- 私有 Pod 的 podspec 正常出现了
之前在 Xcode 工程里的私有组件路径下：
Pods/Development Pods/私有Pod/Pod文件夹
一直没有正确显示组件对应的 .podspec 文件。
在修复私有 Pod 组件自身存在的大小写命名问题后，组件的 .podspec 文件也正常出现了。
这说明之前并不是 CocoaPods 或 Xcode 单纯显示异常，而是路径大小写不一致导致 Xcode / CocoaPods 对组件路径的解析出现了问题。
- Demo 工程重复出现主 Target 的问题消失了
之前 Demo 工程还有一个现象：
Xcode 关闭后重新打开，会出现两个相同的主 Target。
一开始以为这是 Xcode 的 Bug。
但现在回头看，很可能也是路径大小写不一致导致的：
- Xcode 工程引用了一种大小写；
- 磁盘实际目录是另一种大小写；
- Git 或 CocoaPods 生成文件中又可能记录了不同大小写；
- Xcode 重新加载工程时，把它们识别成了不同来源的项目项或 target。
修复大小写一致性后，这类重复 target 的问题也随之消失。
总结
这类问题的本质不是“文件找不到”，而是：
Xcode 工程引用路径、Git index、磁盘真实路径之间的大小写不一致。
在 macOS 默认大小写不敏感的文件系统上，项目可能仍然可以运行，所以这个问题很容易被忽略。
但它会给 Xcode 工程索引、CocoaPods 私有组件解析、CI 构建、多人协作带来隐患。
处理这类问题时，建议遵循几个原则：
- 不要直接用 Finder 修改 Git 仓库中文件或目录的大小写；
- 使用 git mv 两段式重命名；
- 同步修改 project.pbxproj、workspace、scheme、CI、fastlane 等配置；
- 修复后用 git ls-files、git grep 和 xcodebuild 做验证；
- 关闭并重新打开 Xcode，避免旧路径缓存继续影响判断。
一句话总结：
大小写问题不是小问题，它是 Git、文件系统和 Xcode 工程配置三者一致性的问题。只有让三者保持一致，才能真正解决问题。
