【Unity实战】如何使用VS Code在真实iOS设备上调试 Unity应用

简介

本文介绍了如何使用 Visual Studio Code 调试运行在物理 iPhone（通过 USB 连接）的 Unity C# 脚本。流程基于 Unity 的托管调试（PlayerConnection）并通过 USB 端口转发（iproxy）把设备端口映射到本机，VS Code 通过本地端口连接到设备上的 Unity Player。

前置条件

Unity：已安装并打开项目。
Xcode：已安装（用于编译/签名 iOS 应用）。
VS Code ：已安装，并建议安装扩展：
- Debugger for Unity（vstuc，用于托管/C# 调试）
- 如需本地/原生调试，可选 CodeLLDB。
命令行工具 ：
- libimobiledevice（提供 iproxy）：
  bash 复制代码
```
brew install libimobiledevice
```
- 可选 ios-deploy（直接从终端安装并在设备上启动应用）：
  bash 复制代码
```
npm install -g ios-deploy
```

总体步骤

在 Unity 中以支持脚本调试的方式构建 iOS（Development Build + Script Debugging）。
在 Xcode 中打开 Unity 生成的工程并构建到你的 iPhone（或用 ios-deploy 启动）。
使用 iproxy 将设备上的 Unity 管理调试端口（默认 56000）转发到本机：127.0.0.1:56000。
在 VS Code 中使用 Attach to Unity 配置，连接到 127.0.0.1:56000。
在 VS Code 中设置断点并正常调试（断点、单步、变量监视等）。

详细操作

1）在 Unity 中准备构建
- 菜单：File → Build Settings → iOS。
- 勾选 Development Build 和 Script Debugging。
- 点击 Build ，导出 Xcode 工程。
2）在设备上构建并运行
- 在 Xcode 中打开导出的工程，选择已连接的 iPhone，执行 Product → Run（将应用安装到设备并运行）。
- 或使用 ios-deploy（需 device-signed .app）：
  bash 复制代码
```
ios-deploy --bundle /path/to/YourApp.app
```
- 注意：使用 ios-deploy 时，.app 必须为面向 iphoneos 的设备构建并签名。

3）USB 端口转发（设备→本机）
- Unity 的托管调试通常监听设备上的某个端口（默认 56000），在 Mac 上执行：
  bash 复制代码
```
iproxy 56000 56000
```
- 保持该终端窗口打开；iproxy 会显示等待/连接信息。
4）VS Code 启动配置
- 在 launch.json 中添加或确认如下配置（关键是 endPoint 要与转发的本地端口匹配）：
  json 复制代码
```
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Attach to Unity (USB)",
      "type": "vstuc",
      "request": "attach",
      "endPoint": "127.0.0.1:56000"
    }
  ]
}
```
- 在 VS Code 的"运行和调试"面板选择该配置并启动，它将尝试连接到本机 56000 端口（由 iproxy 转发到设备）。
- 【注意】：
  - 如果VS Code连接成功是没有提示的，如果失败会有提示框告知。
  - 一定要在连接成功后再关闭手机上Debug的提示窗口，这时候应用会正式加载。如果在连接前就关闭了，连接成功后应用已经完全加载，有些启动时的逻辑就无法debug了。
5）附加并调试
- 连接成功后，在 VS Code 中设置断点并在设备上操作应用，VS Code 应在断点处停住。
- 若断点未命中，请确保设备上安装的应用是带脚本调试的开发构建且与工程源码匹配（否则重新构建并部署）。

可选：用 tasks.json 自动启动 iproxy（一键转发）

在 .vscode/tasks.json 添加后台任务：

json 复制代码

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "iproxy 56000",
      "type": "shell",
      "command": "iproxy 56000 56000",
      "isBackground": true,
      "problemMatcher": []
    }
  ]
}

在 launch.json 的该调试配置中加入 "preLaunchTask": "iproxy 56000"，实现一键启动转发再附加（注意：ipoxy 为后台任务，调试结束后需手动停止或关闭 VS Code 任务）。

如何定位 .app 文件路径

Xcode 的 DerivedData 目录通常包含构建产物，例如：

复制代码

~/Library/Developer/Xcode/DerivedData/<Project>-<random>/Build/Products/Debug-iphoneos/YourApp.app

在 Xcode：Product → Show Build Folder in Finder 可直接打开产物目录。

或用终端搜索：

bash 复制代码

find ~/Library/Developer/Xcode/DerivedData -name "YourApp.app"

常见问题与排查

"Failed to attach debugger to 127.0.0.1:56000"
- 检查 iproxy 是否正在运行且无错误（终端应显示等待/连接）。
- 确认应用是带 Script Debugging 的开发构建且正在设备上运行。
- 打开 Xcode 的设备日志（Xcode → Window → Devices and Simulators → 选择设备 → View Device Logs），查找类似 Listening for debugger on port 56000 的信息；若端口不同，需要更新 endPoint。
- 如果端口被占用，停止占用程序或将转发改为其他本地端口（例如 56001），并相应修改 endPoint。
断点不生效
- 确保使用 Development Build + Script Debugging，且代码版本与运行在设备上的版本一致。必要时重新构建并部署。
iOS 上直接用 Wi‑Fi 连接调试
- 大多数情况下 iOS 不会直接在 Wi‑Fi 上暴露 Unity 调试端口，USB + iproxy 转发是更可靠的方案。只有在特殊网络/设备（企业配置或越狱）下才可能开通端口。
需要原生/插件层调试
- 若需调试 Objective‑C/Swift 或原生插件，可使用 CodeLLDB 在 VS Code 中配置 LLDB 或直接使用 Xcode 的调试功能。

示例 launch.json（包含 USB 本地转发配置）

json 复制代码

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Attach to Unity (USB)",
      "type": "vstuc",
      "request": "attach",
      "endPoint": "127.0.0.1:56000",
      "preLaunchTask": "iproxy 56000"
    },
    {
      "name": "Attach to Unity (Network)",
      "type": "vstuc",
      "request": "attach",
      "endPoint": "192.168.1.100:56000"
    }
  ]
}

快速检查清单（Debug 前）

Unity：已启用 Development Build + Script Debugging。
设备：已安装并正在运行该应用。
转发：iproxy 56000 56000 正在运行（或已用其他端口转发并更新 endPoint）。
VS Code ：安装 Debugger for Unity，launch.json 的 endPoint 与转发端口一致。