扫描症状：Xcode 27 或 Swift 6.4 升级后，CodeQL 的提取、建库或分析步骤报错，甚至流水线通过但结果不完整。
最快解法：Swift 扫描先固定到 GitHub 支持的 macOS 26 或更早版本与 Xcode 26 或更早版本，暂缓 Swift 6.4；C/C++、C#、Java 可评估 build mode: none，但必须另行验证分析覆盖度。GitHub 于 2026 年 10 月 19 日确认了这些兼容边界；任务启动成功不等于代码已完整分析。(GitHub CodeQL 兼容性公告)
负责 GitHub Actions 与 CodeQL 工作流、需要找出升级后扫描异常原因的 IT 或平台工程负责人，适合从这里开始。
管理 Swift/iOS 项目安全扫描，或规划 Mac 构建资源的负责人，可据此确定工具链回退和节点盘点路径。
先看扫描任务属于哪种工作负载
CodeQL 的故障处理取决于语言、工具链和构建模式，不能只看 Runner 是否为 Mac。下表按最先应采取的处置区分场景；其中 none 是候选方案，不是所有语言的通用替代品。(GitHub 编译型语言与构建模式文档)
| 扫描工作负载 | 已确认的限制 | 优先处置 | 验收重点 |
|---|---|---|---|
| Swift，尤其是 Swift 6.4 | CodeQL 不支持分析 Swift 6.4；Swift 扫描依赖 macOS 与 Xcode 工具链 | 固定到 macOS 26 或更早版本、Xcode 26 或更早版本，并暂缓 Swift 6.4 | 数据库生成、查询分析、SARIF 上传均有证据 |
| 在 Xcode 27 上追踪编译 | 安装 Xcode 27 时，C/C++、C#、Go、Java、Kotlin、Swift 的追踪式提取不可用 | 回退到受支持的 Xcode；部分语言另行评估 none |
实际提取模式、数据库内容和结果范围 |
| 在 macOS 27 上追踪编译 | 相关语言的追踪式提取可能不可用 | 核验实际 Runner 镜像和 Xcode，再复跑对照 | 分辨是操作系统、Xcode 还是项目构建造成 |
| C/C++、C#、Java | 可评估不追踪构建的 none 模式 |
对照 none 与原追踪式扫描的数据库和分析结果 |
生成代码、依赖信息及项目需要的覆盖范围 |
Swift 6.4 的支持边界如何影响扫描？
原因不是某个 Mac 节点配置得不够好。 GitHub 已明确说明，CodeQL 不支持 Swift 6.4，且这一限制不局限于某一台 Mac 或某个 Runner 镜像。编译器能成功编译项目，只能说明构建通过，不能证明 CodeQL 能提取 Swift 代码并完成安全分析；这一兼容边界见上文的 GitHub CodeQL 兼容性公告。
如果 Swift 工具链刚升级，先将扫描任务固定到 macOS 26 或更早版本、Xcode 26 或更早版本，并暂缓 Swift 6.4。这里的“固定”是让扫描环境可复现，不是保证未来升级时无需重新验证。GitHub-hosted 的 Xcode 27 Runner 已运行于 macOS 27，因此仅将 runs-on 写成 xcode-27，不能满足回退要求。(Xcode 27 Runner 发布说明)
Swift 扫描还可能因依赖安装或构建目标不一致而出现提取差异。GitHub 的编译型语言指南指出，Swift 分析使用 macOS Runner；CocoaPods 或 Carthage 管理的依赖，应在生成 CodeQL 数据库前明确安装。排查时不要只看 Xcode 构建日志，还要确认依赖安装是否发生在 CodeQL 数据库生成之前。(GitHub 关于编译型语言构建选项的说明)
Xcode 27 会影响哪些追踪式扫描？
安装 Xcode 27 后，GitHub 确认 C/C++、C#、Go、Java、Kotlin 和 Swift 的追踪式提取不可用。macOS 27 上相关提取也可能不可用，但不应把这句话扩大成“所有项目、所有扫描模式必然失败”。先确认实际扫描走的是追踪式 autobuild／manual，还是不追踪构建的 none。兼容范围以 GitHub 的公告为准。
| 检查维度 | 需要核对什么 | 对恢复扫描的意义 |
|---|---|---|
| Runner 镜像 | 作业实际分配到的 macOS 镜像和架构 | 不要只依赖 macos-latest 等可能变化的标签 |
| Xcode 选择 | xcode-select 结果、所选 Developer Directory、构建日志中的工具链 |
Xcode 27 已安装或被选中时，追踪提取仍可能受限 |
| CodeQL 模式 | 配置中的 build-mode，或实际执行的构建步骤 |
区分追踪式提取故障与 none 模式的覆盖度风险 |
| 数据库与结果 | 数据库生成日志、分析输出、SARIF 文件及上传状态 | 不能以工作流绿色或作业启动成功代替扫描验收 |
目前 Xcode 27 的 GitHub-hosted Runner 镜像使用 macOS 27；它以 xcode-27 和 xcode-27-xlarge 等标签选择。若需做兼容性对照，应把 Runner 镜像和 Xcode 选择分别记录下来，不要仅凭作业名称判断实际环境。可对照 Xcode 27 Runner 镜像说明核实标签和镜像信息。
第一步：固定 macOS 与 Xcode，再做可复核的复跑
不要先改多个变量。 如果 Runner、Xcode 和构建模式同时变化，复跑成功也难以定位究竟是哪一项修复了提取问题。GitHub 建议 Swift 扫描或依赖追踪式构建的工作流固定到 macOS 26 或更早版本与 Xcode 26 或更早版本；在 Actions 中，应固定 Runner 镜像和工具链，而不是依赖自动更新的最新版本。
按以下顺序恢复，并为每次复跑保留配置和日志：
- 盘点扫描目标。 按仓库记录语言、CodeQL 工作流、实际
build-mode、Runner 标签、选定的 Xcode，以及 Swift 版本；不要只搜默认分支配置，矩阵和复用工作流也要一并核对。 - 固定扫描工具链。 Swift 或需要追踪式提取的任务，先使用受支持的 macOS 与 Xcode 组合。将镜像和工具链写入受控配置，避免“最新版本”变动后扫描环境悄然漂移。
- 确认构建模式。 查明当前是
autobuild、manual还是none。如果配置中没写模式，也要从工作流步骤和 CodeQL 日志确认实际执行路径；不同模式可用的语言范围并不相同。 - 单变量复跑。 固定其他输入，只更改 Runner 或 Xcode 等一个变量；比较数据库生成是否完成、扫描语言是否被处理，以及构建是否进入预期提取流程。
- 核验分析与上传。 检查查询分析日志、SARIF 产物、上传步骤和仓库中对应提交的结果。若使用外部生成的 SARIF，还需核验上传动作和分类设置。(GitHub SARIF 上传说明)
- 留存回退记录。 记录临时固定的版本、受影响仓库、例外原因、负责人和重新评估条件；不要把临时兼容策略误记为永久支持承诺。
验收时至少对照源码范围、数据库生成日志、实际运行的查询、SARIF 结果和上传状态。追踪式构建模式会分析工作流中实际构建的代码，因此如果构建目标、生成代码或项目变体改变，结果范围也可能随之改变。(GitHub 关于生成代码告警的说明)
哪些语言可以评估 build mode: none？
GitHub 将 none 列为 C/C++、C# 和 Java 可评估的选项；它不要求追踪构建。但它与追踪式提取并非天然等价：直接从代码库生成数据库，可能无法以同样方式反映实际构建过程中出现的生成代码、编译参数、条件编译分支或依赖上下文。具体语言和模式限制可核对 CodeQL 编译型语言文档。
不要因为 none 能生成数据库，就直接把它当作扫描已恢复。先选有代表性的仓库做对照，并由安全负责人确认以下事项：
- 需要扫描的源码是否进入数据库，生成代码是否属于项目的安全范围；
- Java 的依赖信息是否可获取，C# 的依赖恢复是否符合仓库实际配置；
- 数据库是否覆盖项目需要的目标，查询分析是否正常完成；
- 与原追踪式扫描相比，告警和结果范围的差异是否能解释并被接受；
- 仓库是否包含
none不支持的语言，避免部分语言被忽略后仍将流水线标记为整体通过。
GitHub 文档说明，none 并非所有编译型语言都支持；例如 Kotlin 需要适用的构建模式，不能把 C/C++、C#、Java 的做法外推到 Kotlin 或 Go。按项目语言逐项确认可用模式，再把决定和覆盖度验收结果记录在工作流配置中。
Intel Mac 迁移和 Mac 承载该如何单独评估？
Intel Mac 的 CodeQL 支持计划于 2026 年 12 月中旬弃用，这是独立的环境盘点事项，不是修复 Xcode 27 追踪提取问题的办法。把当前承载节点、使用它的扫描任务、迁移负责人和替代环境记录在同一张清单里；不要因为迁移到另一台 Mac，就假定 Swift 6.4 或 Xcode 27 的支持限制消失。
只有扫描确实需要 Mac 环境、而现有 Runner 又无法满足已验证的工具链和隔离要求时，才进一步比较自有或远程 Mac。自有设备要承担采购、维护和闲置资源管理；远程承载也不能替代版本固定、权限治理、密钥保护和扫描验收，更不能绕过 CodeQL 对 Swift 6.4 的不支持。你可以先查看企业 Mac CI 的适用场景，再按自身采购和资源安排比较远程 Mac 租赁方案；如不需要 Mac 专属构建环境，则不必为了这次兼容问题增加 Mac 节点。
对负责 CI 的团队来说，直接升级到 Xcode 27 可能带来追踪式提取不可用、扫描结果不完整和回滚排查成本；长期自购 Mac 则会增加硬件维护与闲置管理负担。若你已确认扫描必须在 Mac 上运行、但需要临时恢复或隔离测试环境，可以评估 KVMFLUX 的远程 Mac 租赁是否符合工具链与安全要求；它提供的是承载选择，不是 CodeQL 兼容性修复。先自查语言、构建模式和 Runner/Xcode 组合，再决定是否需要租赁 Mac。