Xcode 报错“No such module”，但框架明明存在：该怎么办？

“No such module”：每位 Swift 开发者的熟悉噩梦

您通过 SPM、CocoaPods 或手动方式添加了框架，在 Project Navigator 中能看到它，一切看起来都很完美——但 Xcode 却固执地提示：No such module 'Alamofire'（或任何其他模块）。熟悉吗？如果是——您并不孤单。Stack Overflow 上的原始问题已获得数万次浏览，其评论已成为 iOS 开发者痛苦经历的合集。

在本文中，我们将分析导致 No such module 错误的 10 个真实原因，并展示如何修复它们。最后，您将获得一份清单，可为您节省数小时的烦恼。

为什么 Xcode 找不到模块？十大原因

1. Derived Data——罪魁祸首

Xcode 将项目信息缓存到 Derived Data 文件夹中。如果缓存过时或损坏，编译器会“忘记”已连接的模块。这是首先要检查的事项。

如何修复：

• 关闭 Xcode
• 打开终端并执行：

  rm -rf ~/Library/Developer/Xcode/DerivedData

• 或手动操作：Xcode → Preferences → Locations → Derived Data → 点击箭头 → 删除文件夹
• 重新启动 Xcode 并执行 Cmd + B

2. Build Phases 配置错误

即使框架物理存在于项目中，Xcode 也可能不知道需要链接它。请检查 Link Binary With Libraries：

• 选择目标 (target) → Build Phases
• 展开 Link Binary With Libraries
• 确保您的框架在其中
• 如果没有——点击 + 并添加它

3. Swift Package Manager：分支或版本错误

SPM 是一个方便的工具，但它对版本很敏感。如果您指定了 from: "1.0.0"，而仓库中的版本是 2.0.0，Xcode 可能找不到兼容的模块。

// Package.swift 示例dependencies: [    .package(url: "https://github.com/Alamofire/Alamofire.git", from: "5.6.0")]

该怎么做：

• 转到 File → Packages → Update to Latest Package Versions
• 如果问题仍然存在——删除框架并重新添加
• 检查项目中的 Package Dependencies——模块应为绿色

4. 架构冲突 (Architectures)

旧框架可能仅为 arm64 构建，而您的项目包含模拟器 (x86_64)。随着 Apple Silicon 的出现，这已成为常见原因。

解决方案： 在 Build Settings → Excluded Architectures 中为 Debug 构建添加：

• 对于模拟器：arm64
• 对于设备：$(ARCHS_STANDARD)

5. 框架搜索路径错误 (Framework Search Paths)

如果您手动添加框架，Xcode 需要知道在哪里找到它。请检查 Framework Search Paths：

• Build Settings → Framework Search Paths
• 确保路径指向包含 .framework 或 .xcframework 的文件夹
• 对于 SPM，通常无需指定，但对于手动框架——必须指定

6. 框架未添加到所有目标

项目中可能有多个目标（主应用、小组件、扩展）。如果您只将模块添加到一个目标，其他目标将无法看到它。

检查： 在 Project Navigator 中选择框架 → 右侧检查器 → Target Membership——勾选所有需要的目标。

7. CocoaPods 问题（如果使用）

CocoaPods 是经典工具，但有时在 pod install 后框架无法被正确加载。