Quick 测试框架 CocoaPods 安装问题排查：“No such module ‘Quick‘“ 报错的完整解决方案

• 测试
• 开发工具

Quick 是基于行为驱动开发（BDD）风格的 Swift 与 Objective-C 测试框架，与断言框架 Nimble 配合使用，为开发者提供describe、context、it等描述性测试语法。在通过 CocoaPods 集成 Quick 时，最常遇到的错误之一便是编译期报No such module 'Quick'。本文以官方 日文版 Troubleshooting 文档为核心骨架，结合仓库内的 Quick.podspec、Package.swift 与 安装指南 源码级细节，给出由浅入深的完整排查与解决方案，帮助你在几分钟内恢复测试工程的正常构建。

一、问题现象与根因概述

1.1 典型报错场景

在完成pod install后，当你打开.xcworkspace并尝试编译测试 target 时，Xcode 报出如下编译错误：

No such module 'Quick'

该错误通常出现在测试源文件的第一行import Quick（或 Objective-C 中的@import Quick;）处。也就是说，编译器在module search path（模块搜索路径）中找不到名为Quick的编译产物（.swiftmodule与 framework）。

1.2 为什么 Quick 会以 "module" 形式存在

从仓库根目录的 Quick.podspec 可以看到，Quick 的 CocoaPods 描述文件以 framework 形式暴露模块，关键配置包括：

s.framework = "XCTest" s.requires_arc = true s.pod_target_xcconfig = { 'APPLICATION_EXTENSION_API_ONLY' => 'YES', 'DEFINES_MODULE' => 'YES', 'ENABLE_BITCODE' => 'NO', 'ENABLE_TESTING_SEARCH_PATHS' => 'YES', 'OTHER_LDFLAGS' => '$(inherited) -Xlinker -no_application_extension', }

其中DEFINES_MODULE => 'YES'意味着 Pod 会被编译为带模块定义的 framework，Swift 侧才能通过import Quick使用；同时ENABLE_TESTING_SEARCH_PATHS => 'YES'表明其面向 XCTest 测试环境。因此，"No such module" 报错的本质，是Quick 这个 framework/module 没有被成功编译产出，或者编译产物没有被 Xcode 的模块搜索路径正确索引到。

明确了根因后，下面按官方文档给出的三步解决方案依次操作，通常即可解决问题。

二、解决方案一：关闭并重新打开 Xcode workspace

如果你已经执行过pod install，最简单的一步是：

1. 完全关闭 Xcode（Cmd+Q）；
2. 重新打开项目的.xcworkspace（注意：是 workspace，而不是.xcodeproj）。

为什么这一步可能有效：pod install会改写 workspace 的内容（添加Pods.xcodeproj、更新 scheme 与文件引用）。若 Xcode 在 Pod 安装期间仍处于打开状态，其内部的项目索引（index）与文件监视器往往无法及时感知这些变更，导致编译系统仍在使用旧的模块搜索路径快照。重新打开 workspace 可以强制 Xcode 重新解析工程引用，从而让新生成的Quick.framework目标进入模块搜索路径。

提示：与 CocoaPods 集成的工程必须始终通过.xcworkspace打开，直接打开.xcodeproj时 Pods 依赖不会被加载，同样会引发No such module系列错误。

如果重开 workspace 仍未解决，则进入第二步。

三、解决方案二：彻底删除 DerivedData（含 ModuleCache）

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

官方文档特别强调：请删除~/Library/Developer/Xcode/DerivedData整个目录，因为它包含ModuleCache。

3.1 DerivedData 与 ModuleCache 在报错中的角色

DerivedData是 Xcode 存放所有构建中间产物的目录，包括：

• 各 target 编译出的 object 文件与 framework 产物；
• ModuleCache：模块编译缓存，即各.swiftmodule、Clang module（如@import Quick所需的 module map 缓存）的持久化副本。

当 Quick 或 Pods 依赖升级、Swift/Xcode 工具链版本变化、或 Pod 安装方式变更后，ModuleCache中残留的旧模块产物可能与当前构建配置不匹配，Xcode 在命中过期缓存时就会拒绝重新编译模块，最终以 "No such module" 呈现给开发者。

3.2 删除后的预期行为

删除整个DerivedData后，Xcode 会进入"冷启动"状态，在下次Cmd+B时全量重建所有依赖。这一步会以重新编译 Quick、Nimble 等所有 Pods 依赖为代价，换取干净的模块缓存，是最有效的"核武器"级修复手段。删除后第一次构建耗时较长属正常现象。

如果你希望更精确地处理，也可以只删除DerivedData/<ProjectName>/ModuleCache，但在无法确定具体路径时，按官方文档删除整个DerivedData目录是最稳妥的做法。

四、解决方案三：在 Manage Schemes 中启用相关 Scheme 并显式构建

如果清理缓存后仍然报错，说明问题可能出在target 根本没有参与构建。请按以下步骤操作：

1. 在 Xcode 菜单栏选择Product → Scheme → Manage Schemes…；
2. 在弹出的对话框中，确保以下三个 Scheme 处于勾选（启用）状态：
   • Quick
   • Nimble
   • Pods-<你的项目名>Tests（即测试 target 对应的 Pods 聚合 target）
3. 关闭对话框后，显式按下Cmd+B重新构建。

4.1 为什么 Scheme 未启用会导致该错误

Quick 与 Nimble 是以Pod 依赖形式进入工程的，它们各自是独立的 framework target。CocoaPods 生成的 scheme 默认可能没有被共享或启用；当 scheme 被禁用时，Xcode 不会构建对应的 framework，自然也就不会产出Quick.framework及其.swiftmodule。这解释了为什么即便pod install成功、缓存干净，import Quick依然失败。

4.2 为什么需要同时启用 Nimble

在 Quick 的架构中，Nimble 是 Quick 官方配套的匹配器（matcher）框架，提供expect(...).to断言语法。仓库的 README.md 明确指出：

Quick provides the syntax to define examples and example groups. Nimble provides theexpect(...).toassertion syntax.

二者在 Externals/Nimble 目录下以子模块形式捆绑在 Quick 仓库中，保证 Quick 与 Nimble 版本相互匹配。若只有Quick被启用而Nimble未启用，测试代码中import Nimble同样会报No such module 'Nimble'——这是同一类错误的姊妹变体，务必一并检查。

4.3 显式构建的意义

勾选 scheme 后，先通过Cmd+B显式构建Quick、Nimble与测试 target，可以提前暴露构建链中的其他问题（例如 Pods 版本不兼容），而不是等到运行测试时才报错。

五、从源头排查：核对 Podfile 与安装前提

上述三步来自官方文档，覆盖了绝大多数场景。若问题依旧，建议回到安装源头，逐一核对以下前置条件。

5.1use_frameworks!是否已声明

根据 安装指南 与仓库 README.md 中的 Podfile 示例，CocoaPods 方式集成 Swift 测试框架时必须声明use_frameworks!：

# Podfile use_frameworks! def testing_pods pod 'Quick' pod 'Nimble' end target 'MyTests' do testing_pods end target 'MyUITests' do testing_pods end

若缺少use_frameworks!，CocoaPods 会以静态库形式集成依赖，而 Quick 的 podspec 明确以 framework/module（DEFINES_MODULE => 'YES'）方式构建，二者冲突会导致模块无法暴露给 Swift 编译器。

5.2 CocoaPods 版本与平台要求

从 Quick.podspec 可以确认当前仓库版本（7.6.2）的硬性约束：

s.cocoapods_version = '>= 1.4.0' s.ios.deployment_target = "13.0" s.osx.deployment_target = "10.15" s.tvos.deployment_target = '13.0' s.visionos.deployment_target = '1.0' s.swift_versions = ['5.0']

排查要点：

• 本地 CocoaPods 版本必须不低于1.4.0（可通过pod --version查看，过旧版本请执行sudo gem update cocoapods）；
• 工程 target 的部署版本不得低于iOS 13.0 / macOS 10.15 / tvOS 13.0 / visionOS 1.0；
• 工程使用的 Swift 语言版本需与 Quick 兼容。仓库 README.md 提供了 Swift 与 Quick/Nimble 版本对照表（如 Swift 5.2 对应 Quick v3.0.0 及以上、Nimble v9.0.0 及以上），版本错配也可能导致模块无法正确编译。

5.3 是否使用了正确的 workspace 与测试 target 配置

• 确认你打开的是pod install后生成的.xcworkspace；
• 确认import Quick出现在测试 target（而非应用 target）中。README 的隐私声明指出 Quick 仅用于测试、不应打进提交 App Store 的二进制中；
• 若应用 target 的模块设置异常，参考 SettingUpYourXcodeProject.md：Swift 测试需要将宿主工程Defines Module设为YES，并在测试文件中使用@testable import 你的模块名。

六、同类错误的扩展：SPM 与 Git Submodules 场景

官方 安装指南 还提供了另外两种安装方式，当它们出现类似 "No such module" 错误时，可对照处理：

• Swift Package Manager：在 Xcode 的Package Dependencies面板或 Package.swift 中声明 Quick 与 Nimble 依赖（仓库自身即通过.package(url:from:)声明 Nimble 13.2.0 等依赖）。SPM 场景出现No such module，通常同样可以通过删除 DerivedData 重新解析包解决；注意 Quick 应作为测试 target 的依赖，而非应用 target。
• Git Submodules：按 安装指南 将Quick.xcodeproj与Externals/Nimble下的Nimble.xcodeproj加入 workspace，并在测试 target 的Link Binary with Libraries中链接Quick.framework与Nimble.framework。该场景下报错多因漏链接 framework 或未将Quick.xcodeproj加入 workspace。

此外，若你使用的测试框架配置类（QuickConfiguration）未被正确加载，可参考 ConfiguringQuick.md 检查configure(_:)的覆写方式——配置类缺失不会直接导致No such module，但会让全局beforeEach/afterEach钩子失效，容易被误判为集成失败。

七、解决步骤速查表

按上述顺序逐级排查，No such module 'Quick'这类 CocoaPods 集成问题通常能在前三步内解决。官方文档 英文版 Troubleshooting 与 日文版 Troubleshooting 保持同步内容，多语言读者均可直接参考；更完整的安装步骤见 InstallingQuick.md。

• 测试
• 开发工具