核心用法
swiftfindrefs 是一款基于 Xcode IndexStoreDB 的命令行工具，用于精确查找 Swift 项目中某个符号（类、结构体、枚举、协议、函数、变量等）的所有引用位置。与 grep 或 IDE 搜索不同，它直接查询编译器生成的索引数据（DerivedData），能够准确识别符号的语义关联，而非简单的文本匹配。
标准调用方式需指定项目名称、符号名称和符号类型：
swiftfindrefs --projectName MyApp --symbolName MyClass --symbolType class
输出为去重后的绝对文件路径列表，可直接用于脚本管道处理。
显著优点
1. 语义级精确性：基于编译器索引，避免同名符号、注释、字符串误匹配等问题
2. 跨模块完整性：能发现跨 target、跨 module 的引用，文本搜索难以覆盖
3. 重构安全保障：强制 workflow 要求先运行工具、仅编辑返回文件，防止遗漏
4. 脚本友好：纯路径输出，便于自动化处理（批量添加 import、重命名等）
潜在缺点与局限性
1. 环境依赖严格：必须 macOS + Xcode，需成功构建过项目（DerivedData 存在）
2. 无法处理未编译代码：新增文件或修改后未构建的代码不在索引中
3. 索引损坏风险：DerivedData 异常时需清理重建，工具本身无修复能力
4. 仅限 Swift：不支持 Objective-C 等其他语言的混合项目交叉引用
5. 无上下文信息：仅返回文件路径，不显示具体行号或调用上下文
适合人群
- 进行大规模 Swift 重构的开发者
- 需要安全删除或重命名公共 API 的维护者
- 处理多 module 项目 import 修复的自动化脚本场景
- 追求代码变更确定性的团队
常规风险
- 索引过期：若代码已修改但未重新构建，返回结果可能遗漏新引用或包含已删除引用
- 符号类型误指定：
--symbolType错误可能导致找不到目标或返回错误结果 - 路径权限问题：DerivedData 位于系统目录时可能遇到读取权限限制
- 误用文本搜索替代：违反 Rules 使用 grep 补充查找会导致重构不完整，引发运行时错误