在macOS系统使用Unreal Engine 5.4.3时，将C++项目放置在外部存储卷会触发构建失败，UnrealBuildTool输出报错如下：

Setting up bundled DotNet SDK
/Users/Shared/Epic Games/UE_5.4/Engine/Build/BatchFiles/Mac/../../../Binaries/ThirdParty/DotNet/6.0.302/mac-arm64
Running dotnet Engine/Binaries/DotNET/UnrealBuildTool/UnrealBuildTool.dll -projectfiles -project=/Volumes/xxx/Projects/Unreal/MyProject/MyProject.uproject -game -rocket -progress
Log file: /Users/xxx/Library/Application Support/Epic/UnrealBuildTool/Log_GPF.txt

Generating XCode project files:y
Discovering modules, targets and source code for project...
Errors generated while parsing '/Volumes/xxx/Projects/Unreal/MyProject/Source/MyProject/._MyProject.Build.cs'
/Volumes/xxx/Projects/Unreal/MyProject/Source/MyProject/._MyProject.Build.cs(1,1): error CS1056: Unexpected character '/Volumes/xxx/Projects/Unreal/MyProject/Source/MyProject/._MyProject.Build.cs(1,46): error CS1056: Unexpected character '�'
/Volumes/xxx/Projects/Unreal/MyProject/Source/MyProject/._MyProject.Build.cs(1,47): error CS1056: Unexpected character '/Volumes/xxx/Projects/Unreal/MyProject/Source/MyProject/._MyProject.Build.cs(1,158): error CS1056: Unexpected character '�'
/Volumes/xxx/Projects/Unreal/MyProject/Source/MyProject/._MyProject.Build.cs(1,161): error CS1056: Unexpected character '�'
/Volumes/xxx/Projects/Unreal/MyProject/Source/MyProject/._MyProject.Build.cs(1,162): error CS1056: Unexpected character '�'

将项目放在本地Documents文件夹或创建蓝图项目时无此问题，Xcode、VSCode、CLion等IDE均存在相同报错，疑似字符编码问题但未找到对应配置项。

解决建议 #

• 清理外部存储卷的隐藏元文件
  macOS会在外部存储卷生成._开头的隐藏元文件（比如报错里的._MyProject.Build.cs），这些是系统存储文件属性的资源分支，UnrealBuildTool误将其当作源码文件解析导致编码错误。操作步骤：

  1. 打开终端，进入项目Source目录：cd /Volumes/xxx/Projects/Unreal/MyProject/Source/MyProject
  2. 删除所有._开头的文件：rm -rf ._*
  3. 若要永久禁用外部存储卷的元文件生成，终端执行defaults write com.apple.desktopservices DSDontWriteNetworkStores -bool true，重启系统后生效（该命令对网络存储、USB存储均适用）

• 检查外部存储卷的文件系统格式
  确保外部存储卷使用APFS或Mac OS Extended（Journaled）格式，非原生文件系统（如NTFS、FAT32）可能引发文件编码或元文件处理异常，可通过「磁盘工具」查看和格式化存储卷。

• 修改UnrealBuildTool的文件过滤规则
  备份Unreal Engine安装目录下的Engine/Source/Programs/UnrealBuildTool/ProjectFiles/Xcode/XcodeProjectGenerator.cs文件，编辑原文件时在遍历源码文件的代码段中添加判断，跳过文件名以._开头的文件。

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