调试

当命令行为不符合预期时，Tuist 提供了多种工具来帮助你诊断问题。

会话数据

如果命令调用没有产生预期结果，你可以通过检查会话来诊断问题。CLI 将日志转发到 OSLog 和文件系统。

在每次运行时，它会在 $XDG_STATE_HOME/tuist/sessions/{uuid}/ 创建一个会话目录，其中如果未设置环境变量，$XDG_STATE_HOME 的值为 ~/.local/state。你也可以使用 $TUIST_XDG_STATE_HOME 设置 Tuist 特定的状态目录，它优先于 $XDG_STATE_HOME。

每个会话目录包含：

logs.txt - CLI 会话的文字日志
network.har - HTTP Archive (HAR) 文件，包含会话期间发出的所有网络请求和响应

可视化 HAR 文件

HAR 文件记录了会话期间发出的所有 HTTP 请求和响应，对于调试服务器通信问题很有用。你可以使用多种工具打开 HAR 文件：

Proxyman：用于查看和分析 HTTP 流量的原生 macOS 应用。通过 File > Import 导入 HAR 文件。
浏览器开发者工具：Chrome、Firefox 和 Safari 都支持在其 Network 标签中导入 HAR 文件。
HAR Viewer：基于 Web 的 HAR 文件查看器。

默认情况下，当执行意外退出时，CLI 会输出会话路径。如果没有，你可以从上述路径（最近的会话目录）找到会话数据。

超过 5 天的会话目录会被自动清理。

持续集成

在 CI 环境中（环境是一次性的），你可能希望配置 CI 流水线导出 Tuist 会话数据。导出制品是跨 CI 服务的常见功能，配置取决于你使用的服务。例如，在 GitHub Actions 中，你可以使用 actions/upload-artifact 操作将会话数据作为制品上传：

name: Node CI

on: [push]

env:
  TUIST_XDG_STATE_HOME: /tmp

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
      # ... 其他步骤
      - run: tuist generate
      # ... 对项目做些什么
      - name: Export Tuist session data
        if: failure()
        uses: actions/upload-artifact@v4
        with:
          name: tuist-sessions
          path: /tmp/tuist/sessions/

缓存守护进程调试

要调试与缓存相关的问题，Tuist 使用子系统 dev.tuist.cache 通过 os_log 记录缓存守护进程操作。你可以使用以下命令实时流式传输这些日志：

log stream --predicate 'subsystem == "dev.tuist.cache"' --debug

这些日志也可以通过在 Console.app 中过滤 dev.tuist.cache 子系统来查看。这提供了关于缓存操作的详细信息，可以帮助诊断缓存上传、下载和通信问题。