Xcode 文件资源管理深度解析：Create Folder References 与 Apply once to Folder 的正确用法
在日常 iOS 开发中，我们经常会将一些本地资源（图片、音频、JSON 配置文件等）打包进 App Bundle。然而，当我们尝试访问这些文件夹时，可能会遇到这样的困惑：
明明我在 Xcode 里看到了
Music文件夹，但运行时Bundle.main.url(forResource: "Music", withExtension: nil)却找不到？
如果你也遇到类似问题，本文将帮你彻底厘清这背后的机制——包括 Create folder references vs Create groups 的区别，以及 Apply once to Folder vs Apply to each File 对资源打包的影响。
一、Create folder references vs Create groups
在 Xcode 中添加资源文件时，我们会看到两个选项：
🟡 Create groups（默认，黄色文件夹）
- 仅是逻辑分组，不会改变文件的物理路径。
- Xcode 编译时会将文件夹打散，把里面的文件直接复制到 bundle 根目录。
- 因此文件夹的结构不会被保留。
假设我们在项目中有：
Resources/
└── Music/
├── calm.mp3
└── ocean.mp3
使用 Create groups 添加后，打包结果会变成：
App.app/
├── calm.mp3
└── ocean.mp3
这意味着 Bundle.main.url(forResource: "Music", withExtension: nil) 会失败，因为 bundle 内根本没有 Music 这个文件夹。
🔵 Create folder references（蓝色文件夹）
- 会创建真实的文件夹引用。
- 编译时，Xcode 会把整个文件夹原封不动地复制到 app bundle。
- 文件夹层级在运行时依然存在。
打包结果：
App.app/
└── Music/
├── calm.mp3
└── ocean.mp3
此时你就可以使用以下代码成功访问文件夹：
if let folderURL = Bundle.main.url(forResource: "Music", withExtension: nil) {
print("✅ 找到文件夹路径：(folderURL.path)")
}
二、Apply once to Folder vs Apply to each File
即使使用了 folder references，有时候依然会“找不到文件夹”，问题常常出在 Build Rules 的配置上。
在 Identity and Type → Build Rules 中，Xcode 会针对每个文件资源应用不同的策略：
1️⃣ Apply to each File
- 对文件夹中的每个文件逐一操作。
- 如果是 folder reference，这种方式会展开文件夹并逐个复制文件。
- 最终在 bundle 中 只保留文件，不保留文件夹结构。
结果：
App.app/
├── calm.mp3
└── ocean.mp3
导致 Bundle.main.url(forResource: "Music", withExtension: nil) 依然找不到。
2️⃣ Apply once to Folder
- 将整个文件夹视为一个整体，只复制一次。
- 文件夹结构和层级会完整保留。
- 运行时可以直接通过文件夹路径访问。
结果：
App.app/
└── Music/
├── calm.mp3
└── ocean.mp3
✅ 这才是我们想要的正确结构。
三、正确的设置组合
| 文件夹类型 | Apply 设置 | 打包后结构 | 是否能访问文件夹 |
|---|---|---|---|
| Create groups | Apply to each File | 文件被打散 | ❌ |
| Create folder references | Apply to each File | 文件夹被展开 | ❌ |
| Create folder references | Apply once to Folder | 保留原始层级 | ✅ |
四、实际示例
以下是一个递归读取文件夹中所有文件的 Swift 示例：
/// 递归读取目录下所有文件（只返回文件，不返回目录）
func getAllFilesRecursive(in directoryURL: URL) -> [URL] {
var results: [URL] = []
guard directoryURL.isFileURL else {
print("❌ 不是文件 URL: \(directoryURL)")
return results
}
let fm = FileManager.default
do {
let items = try fm.contentsOfDirectory(at: directoryURL,
includingPropertiesForKeys: [.isDirectoryKey],
options: [.skipsHiddenFiles])
for item in items {
let resourceValues = try item.resourceValues(forKeys: [.isDirectoryKey])
if resourceValues.isDirectory == true {
// 目录 -> 递归进入
results.append(contentsOf: getAllFilesRecursive(in: item))
} else {
// 文件 -> 添加
results.append(item)
}
}
} catch {
print("⚠️ 读取目录失败: \(error) — \(directoryURL.path)")
}
return results
}
五、总结
“Create folder references 决定是否保留目录结构，
而 Apply once to Folder 决定是否整体复制该目录。”
可以简单记住一句话：
蓝色文件夹（folder reference）+ Apply once to Folder = 能在运行时找到完整文件夹。
💡小贴士
- 如果只是想加载单个资源（例如图片），用默认的 Create groups 即可。
- 但如果需要在运行时访问整个目录（例如读取一批音频、JSON 或配置文件），务必使用 Create folder references 并设为 Apply once to Folder。
标签： #iOS开发 #Xcode技巧 #资源管理
喜欢这篇文章的话，点个赞或收藏吧，让更多开发者不再踩坑。🚀
